DEV Community: Sebastien Castiel

[Boost]

Sebastien Castiel — Wed, 03 Sep 2025 17:28:24 +0000

Sebastien Castiel

Sep 3 '25

Seven Hours, Zero Internet, and Local AI Coding at 40,000 Feet

#programming #ai #vibecoding

Comments 13

5 min read

Seven Hours, Zero Internet, and Local AI Coding at 40,000 Feet

Sebastien Castiel — Wed, 03 Sep 2025 17:23:45 +0000

Seven hours on a plane, zero internet, and a curiosity about local AI coding. That's how I found myself downloading 13GB of AI models in an airport lounge, preparing for what would become an accidental experiment in offline development.

This wasn't a research project or a formal comparison of existing solutions. I was heading back from vacation with a long flight ahead and wanted to avoid getting bored. The idle question nagging at me: what would it be like to have a coding assistant totally local, or at least that I can run on my own infrastructure, without paying for tokens or subscriptions? Plus, it sounded fun.

So I decided to find out where we are on this path.

What I Threw Together Before Takeoff

I started from a basic Next.js project with the dependencies I like: TailwindCSS, Zod, ts-pattern, etc. My goal was to use a stack I already know very well, so I wouldn't be fighting unfamiliar tools while experimenting with local AI.

Then, with the quest for a local LLM, came the real trial and error. I tried Devstral from Mistral, Qwen3, with Crush, OpenCode and Ollama-code. After several failed attempts, gpt-oss was actually the only one I was able to make work, and only with OpenCode¹. It's not that I did extensive research to compare solutions – this was purely what I could get functioning in the time I had.

So I set up Ollama with gpt-oss downloaded – all 13GB of it. My machine is a MacBook Pro M4 Pro with 24GB of RAM, which I should mention upfront because the hardware requirements turn out to matter quite a bit.

For the project itself, I chose something deliberately simple: an app to track subscriptions to recurring services like Netflix or your gym. Basic CRUD operations, nothing fancy. I decided to make the app rely on the browser's local storage to persist data, instructing the assistant to create an abstraction on top of it so I could migrate to a proper API or Supabase later.

Seven Hours at 40,000 Feet

For my experiment, I used the approach I described in Turning Claude Code Into My Best Design Partner: first I ask the assistant to plan the feature, following up with changes if necessary. When the plan looks good, I ask to put it in a Markdown file in a plans folder. Then I ask it to start implementation using the plan and update the plan document with progress, making it a living document.

I was pleasantly surprised that the planning was more than okay, at least for my basic use case. Maybe it would be more complicated for a more complex feature, but here I accepted the suggested plans almost at first try!
The speed reality hit quickly: the local setup was about 4-5x slower than Claude Code², so you have to be patient. Good thing planes have movies to watch between the prompts.
The energy consumption was the real surprise. Not only were my thighs quite burning from the laptop heat, but the power offered by the plane – with its shitty plug – wasn't able to compensate for the energy that the local model needed. I had to take breaks at some points to let my laptop's battery charge. Forget about battery-powered coding sessions.
Finally, the code quality was usually 95% correct, but fixing the remaining 5% was tedious. Various issues kept cropping up: ESLint problems, using any instead of proper types, or some UI elements that got removed from one iteration to another, like buttons that would just disappear. In a professional project, I would have fixed these issues myself for speed reasons. Here, I wanted to go all in with the AI-assisted approach, but the AI was perfectly capable of fixing the problems – it just took a lot of time and iterations.

👆 The subscriptions list in the resulting app. Not an app I would use everyday, but it works :)

During my 7-hour flight, I worked on the app for about 3-4 hours (the rest being meals, naps and movies). I was able to build a basic app with a form to add a subscription, a subscription list showing the total for the current month plus expired and future subscriptions, an edit button, and a way to delete subscriptions. The UI was very basic and not very UX-friendly, but it worked.

The Broader Reality Check

When I started using OpenCode with gpt-oss, I was pleasantly surprised to see that it just worked. Not perfect, but pretty good. And all on my machine only! No need to check my Claude quotas or API keys usage. There was something liberating about that complete independence.

The latency that a local model implies, plus the energy consumption, make it hard to imagine going fully local for now. The hardware requirements are real – this isn't running smoothly on your average developer laptop. But let's hope performance and efficiency will improve over time.

Finally, I would have expected to have more documented options at my disposal for local AI coding. I was able to find some blog posts, some outdated, but official documentation was lacking with OpenCode³, Crush⁴, and similar tools.

The next thing I'd like to try is using OpenAI's GPT-OSS with OpenCode, but not locally: either from OpenAI's API, or from a server with more power than my laptop.

What This Actually Means

Looking at this experiment, the most important takeaway for practitioners is a mix between "local AI coding is surprisingly viable today" and "it's still too early but getting close."

It's really about having the option to go local, plus the hope that someday the models will be more efficient and the hardware more AI-optimized, so that everything can run locally and smoothly without consuming too much energy or destroying batteries.

The current state is encouraging for simple projects but still feels early for serious professional work. The trade-offs are real: you need serious hardware, you'll burn through battery life, and you'll move slower than with cloud-based tools. But the foundation is there, and it's more solid than I expected.

Back to Reality

Landing, turning WiFi back on, returning to Claude Code – the speed difference was immediately apparent. But something had shifted during those seven hours offline. Local AI coding moved from "maybe someday" to "definitely possible, with caveats."

This vacation experiment accidentally revealed where we are on the path to truly local development assistance. We're not there yet, but we can see it from here. And sometimes, that's the most interesting place to be.

This post was first published on the blog Between the Prompts. Check it out and subscribe to the newsletter to be the first reading the new posts 😉.

I used this guide to set up OpenCode with gpt-oss using Ollama. ↩
Only my personal feeling, it's hard to get a precise benchmark. ↩
See this short section about setting up OpenCode with Ollama. ↩
This section in Crush's documentation explains how to use it with Ollama, but all models I've tried using generated errors related to tool-calling… ↩

Turning Claude Code Into My Best Design Partner

Sebastien Castiel — Wed, 27 Aug 2025 13:56:13 +0000

When I first started using Claude Code, I had a naive approach to working with it. I would describe the task directly in the prompt, press Enter, and cross my fingers. If the agent made mistakes, I would tell it how to fix them. For small tasks, this can be good enough, but as the task grows in complexity, this approach reveals several significant drawbacks.

When Simple Doesn't Scale

The first problem is that the conversation becomes the only source of truth about the task. This means a new message can override instructions from an old one, but it isn't always clear when this happens, which can cause mistakes by the agent.

Additionally, the context size for the agent is limited. The more the conversation grows, the more information from the beginning can be "forgotten," even though Claude Code has a capacity for "compacting" the conversation that's supposed to improve this issue.

For these reasons, I started experimenting with an approach I'd heard about: asking Claude Code to start by writing a plan document. This document becomes the source of truth instead of a sprawling conversation. When I find the plan document good enough, I've taken the habit of clearing the conversation to start fresh with just the plan as context.

Creating the Initial Plan

My first prompt is usually to give Claude Code a description of the feature it should implement (or bug it should fix, or the refactoring it should do) with all the details I have in mind. If I already have an idea of the implementation, I can give it some pointers to existing files for reference. However, I try not to give it too many implementation instructions because I want it to make suggestions and contribute to the design process.

I want to implement a query builder. The page will be displayed as two columns. In the first one, a first box will let the user select a view (for now only one view: "Volume Metrics"), a second box to select fields ("field 1", "field 2", "field 3"), and a third one to add filters (don't fill it yet). The right column will display first the query as human readable, then a table with the query results. (to be continued)

I also try to refer to existing plans for features implemented previously. I don't have a formal template, but I don't really need one as long as I have other plans to reference as examples.

(continuing) Check out the previous plan in @plans/chat-playground.md to know about routing and architecture details. (to be continued)

I expect to see several key elements in the document. First, a rephrasing of the feature description I gave it, which helps ensure we're aligned on requirements. Second, details on how the feature will be implemented—usually it includes some pieces of code or pseudo-code without me having to tell it to do so. Finally, commands to run to make sure the code quality is acceptable, including type checking, linting, and tests.

(continuing) Write a plan in @plans/query-builder.md, and let me validate it before starting the implementation.

The Collaborative Design Process

Sometimes, I'm not satisfied with the suggested implementation. In this case, instead of updating the plan, I tell it why it's wrong, expecting it to change its approach.

The page should be a subroute of /explore, not /review. Also, it should be accessible only to users with the "admin" role.

It also happens that after a few back-and-forth exchanges, I realize the first suggested approach was better than the one I had in mind. This process is much more efficient than if I had started writing the code by myself and realized my approach was wrong later.

It's a bit like discussing the plan with a colleague each time I'm about to start a new feature. More specifically, it's like challenging my implementation plan with a junior colleague (or one who doesn't know the codebase as well) who will question my choices. The dynamic reminds me of the rubber duck debugging technique, where explaining your approach helps you think through problems. However, it won't suggest a radically different approach unless I specifically ask it to, which I have never tried.

But the plan document isn't just a blueprint for the implementation. I discovered that Claude Code is much more efficient when it considers it as a living document.

The Living Document Approach

The key insight is that I don't just ask Claude Code to write the plan—I also ask it to make it a living document while implementing the feature. I explicitly ask it to update the plan during implementation because the implementation process, and especially the type checking, linting, or test processes, can reveal that some parts of the original plan were incorrect.

I've developed the habit of asking it to check that the plan is up to date each time it commits code, treating plan updates the same way as running quality checks.

Make sure the plan is up to date, and commit changes.

This living document approach solves a fundamental problem with AI development: context limits. With an up-to-date plan document, I can start a fresh conversation and simply ask Claude Code to continue the implementation. This usually works great—just the document is usually enough context for a new session to pick up exactly where the previous one left off.

Continue the implementation documented in @plans/query-builder.md.

My Review Process

When the implementation starts, I review changes along the way to ensure everything is progressing correctly. However, if I'm satisfied with the progress, I can let it continue without checking as often. When reviewing the final code, the updated plan document gives me helpful hints about the technical choices that were made during implementation.

Surprisingly, I think that the fact that I need to plan my features carefully before rushing into implementation is making me a better developer overall. This happens simply because it forces me to document the implementation and think it through before jumping into code. I also find myself explaining my reasoning more clearly because I have to write it down for the AI, whereas with colleagues I would typically discuss things in person or via video call.

From Chaos to System

This workflow systematically addresses the fundamental problems I encountered with the naive approach: it creates a clear source of truth, eliminates context limit issues, and forces better architectural thinking. The living document becomes both the specification and the implementation log, creating a complete record of not just what was built, but why and how it was built.

The result is a development process that's more thoughtful, more documented, and more reliable.

AI isn't just serving as implementer.

It becomes a collaborative design partner.

This post was first published on the blog Between the Prompts. Check it out and subscribe to the newsletter to be the first reading the new posts 😉.

13 tips for better Pull Requests and Code Review

Sebastien Castiel — Tue, 17 Oct 2023 15:42:40 +0000

In many years of writing and reviewing code, I learned a few secrets to craft better pull requests and review code more efficiently.

I poured all these secrets into my new book Pull Requests and Code Review, but you’ll find here a preview with these 13 tips, that you can already use in your developer activity.

Can you think of more tips? Share them in comments 😉

1. Create your PR before the code is ready for review

A PR draft helps you organize your ideas and document your progress, while you’re still working on your feature.

2. Make people want to review your PR

The best way to get a quick and efficient review is to keep your PR small and well documented (with all the necessary context). You’ll also increase you chances for future PRs by delivering great code now!

💡 Find all these tips with and more, with more real-life examples and actionable insights in my free book Pull Requests and Code Review: Strategies, Techniques, and Best Practices for Collaboration.

3. Be your PR’s first reviewer

Put yourself in the shoes of your reviewer, anticipate questions and use comment your own code when you think it can help them.

4. Assign the right reviewers to your PR

Don’t assign your PR to the entire world. Choose your reviewers carefully to get a relevant review, without waiting too long for approval.

5. Be responsive to comments

Be open to feedback, ask for clarification, say when you disagree (with respect), and always respond to comments.

6. If you want people to review your PRs, you have to review theirs

Everybody has many PRs to review and little free time to. If you review other PRs, you increase the chances of getting yours reviewed too.

7. You can review code even if you are a junior developer

As a junior developer, you can let others know when you don’t understand part of the code, as it should be understandable by any developer in the team.

More about it in my post How to give code review as a junior developer?.

8. Check the right things during code review

Code review’s goal is to check for bugs and edge cases, and challenge the implementation. It should neither be used to nitpick about minor formatting or styling preferences, nor for large-scale architectural discussions.

9. Use the right tone in your comments

Use “why not” instead of “you should”, be open and positive and always suggest an alternative when you ask for a change.

10. Be clear about whether a change is required for you to approve the PR or not

Not all comments require a change, and not all asked changes are required for the PR to be approved. Be clear in your comment if the change isn’t urgent.

11. Review your review before submitting it

Before making your review public, re-read each comment: check for the tone you use and ensure you provide all the context to help the PR submitter.

12. Approve the PR when the submitter made all the changes you asked

You don’t want the reviewer to wait for your approval two days after they made all the changes you asked. When you review it, assume you’ll approve it as soon as all the fixes are made.

13. Some conflicts can’t be solved in comments

When a comment thread becomes a debate in your PR, you’d better cut it off and suggest to continue the discussion elsewhere, e.g. in a Slack thread. If necessary, dedicate a meeting to it, and/or involve a third-party.

That’s it! What did you think of these tips? Can you think of one tip you’d like to give other developers?

Share them here in comments 👇

If you liked these tips and want to learn some more, check out my book Pull Requests and Code Review, it’s free!

The simplest example to understand Server Actions in Next.js

Sebastien Castiel — Tue, 08 Aug 2023 19:26:12 +0000

Server Actions are a new feature in Next.js. The first time I heard about them, they didn’t seem very intuitive to me. Now that I’m a bit more used to them, let me contribute to making them easier to understand.

I tried to create the smallest possible example to help developers understand what they are and what they can be used for. The result is this example, which consists of two files:

// client-component.tsx
'use client'
import { useEffect, useState } from 'react'
import { getInformationFromTheServer } from './actions'

export function ClientComponent() {
  const [info, setInfo] = useState('')

  useEffect(() => {
    getInformationFromTheServer('World').then((res) => setInfo(res))
  }, [])

  return (
    <p>
      This comes from the server: <code>{info}</code>
    </p>
  )
}

// actions.ts
'use server'

export async function getInformationFromTheServer(name: string) {
  return `Hello ${name}!`
}

The use case is as follows: In a client component, we’d like to get some information from the server. Without server actions, we’d have to:

Either get this information as a prop passed by the parent component (assuming it is a server component),
Or create an API route and call it from the client component using fetch. Server actions are similar to the second option, but with a shortcut: the API route will be created by Next.js for us.

In our example, the server action is the function getInformationFromTheServer, declared in actions.ts (server actions cannot be defined in the same file as a client component). Like any server action:

It is declared as async (it has to, even if it doesn’t perform any async operation),
It uses the directive 'use server' (either at the top of the file or the top of the function).

💡 Tiny interruption in this post: if you’d like to learn how to use React and Next.js to create powerful applications, check out my online course or my live workshop 😉.

From the client component, we can call the function like any other side effect (async) function: in a useEffect or an event callback.

It looks like we’re just calling a function, so you might wonder why everybody is making such a fuss about server actions… Look closer: from a client component, we call a function stored on the server.

This means that it isn’t just a function call: there is actually an HTTP request made to the API to call the function. You can see it in the Network tab of your DevTools:

The endpoint is at the same path as your current page but:

Uses the POST method,
Needs some headers, such as the Next-Action one, containing some kind of ID for the server action,
Gets the parameters to pass to the function from the request body (as JSON).

When you copy the server action ID from the headers, you can even call the API endpoint using cURL:

$ curl 'http://localhost:3001/getting-info-from-server' \
  -H 'Content-Type: text/plain;charset=UTF-8' \
  -H 'Next-Action: da9f55acc16563503a57a4fdfe567f8770898818' \
  -X POST --data-raw '["World"]'
0:["$@1",["development",null]]
1:"Hello World!"

Note: In Chrome DevTools, at the time I’m writing this post, it looks like it isn’t possible to see the result of the request, as it is sent using HTTP streaming. It works well with cURL 😉.

As you can see, there is nothing magical about server actions:

Next.js takes our getInformationFromTheServer function,
It makes it callable through a specific API endpoint,
From the client component, when we think we are calling the function we defined, we actually call a function generated by Next.js which deals with the necessary API call for us.

If you are familiar with distributed computing patterns, you can notice that server actions offer a remote procedure call (RPC) pattern for Next.js applications.

The cURL example shows something very important about server actions: anyone can call existing server actions with any parameter they want! This means that the parameters received by the server actions must be validated, just like any parameter sent to a classic API route.

This is especially counter-intuitive when using TypeScript. Even if you declare that your function must get a string parameter, this function will be made available to the rest of the world, even to big bad hackers who want to send a number instead.

With that in mind, server actions still offer a nice pattern to get information from the server, especially in a client component. From there, we can imagine cool and more complex use cases:

Mutating data on the server (e.g. in a database),
Sending an email,
Processing data entered in a form, etc.

And, like in any other API endpoint, we can, of course, check user authentication to ensure we don’t allow anything for anyone.

I hope that server actions are now a bit clearer to you!

When you understand how they work, you can find many resources about how to use them in real-life applications:

Build a Guestbook from the 2000s with React Server Components and Server Actions

Sebastien Castiel — Wed, 05 Jul 2023 12:51:05 +0000

React is living something these days. Although it was created as a client UI library, it can now be used to generate almost everything from the server. And we get a lot from this change, especially when coupled with Next.js.

In this short tutorial, we’ll use React Server Components and Server Actions to build something from the early '00s: a guestbook!

I bootstrapped a Next.js app with TypeScript and the app router. As I don’t want to care about the CSS, I used Water.css. And to store the messages, I went with Vercel KV (which may not be the right tool for this kind of use case, but is plenty enough for the purpose of this post). The complete source code of the demo project is available on GitHub.

Fetching the messages from a Server Component

Let’s start with displaying the existing messages. With a classic React component, we’d have to declare a local state, perform a fetch request in a useEffect, etc. With Next.js’ server-side rendering, we could declare a getServerSideProps function to fetch the messages first.

With server components, we can fetch the messages from the component itself:

export async function MessageList() {
  const messages = await fetchMessages()

  return (
    <>
      <h2>Last Messages</h2>
      {messages.map(({ id, name, content, date }) => (
        <blockquote key={id}>
          <div>{content}</div>
          <small>{`–${name}, ${formatDate(date)}`}</small>
        </blockquote>
      ))}
    </>
  )
}

Looks odd to you? It should! The component is declared async, and fetches data from its body, without any useEffect?

This is what server components let us do. As a server component can be rendered only on the server, we can perform asynchronous operations such as querying a database, making HTTP requests, or even read from the filesystem.

As a consequence, notice how the component is easy to read, even by someone who’s not as familiar with React as you are. We fetch the data, and we display it. That’s it.

What if fetching the messages takes a few seconds? Does it mean that the page will take that much time to load? Fortunately, no. We can take advantage of React’s Suspense to display a nice loading message while the component is still fetching the data.

In the page displaying messages, we can wrap our MessageList component with Suspense, with a fallback message.

export default function MessagesPage() {
  return (
    <>
      {/* ... */}
      <Suspense fallback={<p>Loading messages…</p>}>
        <MessageList />
      </Suspense>
    </>
  )
}

For a deeper dive in Server Components and Suspense, have a look at my previous post Display a view counter on your blog with React Server Components.

So this is how we can read data from a server component, but is there something similar for writing data so we can post new messages as easily?

Submitting forms with Server Actions

Server components let us fetch data without having to set up a flow with useEffect. We can do something similar to submit data from a form, thanks to Server Actions.

Let’s start with this basic form:

export function MessageForm() {
  return (
    <form>
      <h2>New Message</h2>

      <label htmlFor="name">Your name:</label>
      <input type="text" id="name" name="name" required minLength={3} />

      <label htmlFor="content">Your message:</label>
      <textarea id="content" name="content" required minLength={3} />

      <button type="submit">Send</button>
    </form>
  )
}

As you can see, there is nothing fancy here: two fields, a button, and some validation attributes.

To submit this form, we usually have two options:

use the action attribute to use an API endpoint handling the form data,
manually make a fetch request to call this API endpoint.

In the first scenario, the page would reload when the user submits the form, which is something we may want to avoid. The second scenario is the one we tend to prefer in React apps, but is a bit more complex to set up.

With server actions, we can get the best of both worlds. We can create a function that will be called on the server when the form is submitted:

async function submitMessageForm(formData: FormData) {
  'use server'

  await postMessage({
    content: formData.get('content'),
    name: formData.get('name'),
  })
}

By adding 'use server' in the function body, we declare it as a server action. We can then associate it with the form by using the action attribute:

return (
  <form action={submitMessageForm}>

Note: to use server actions in a Next.js project, you need to enable them in your next.config.js file:

experimental: { serverActions: true },

What about form data validation? We declared some validation attributes on the form itself, but as always it doesn’t prevent us of validating the data on the server:

// Validation example using a Zod schema
const message = formDataSchema.parse({
  content: formData.get('content'),
  name: formData.get('name'),
})

await postMessage(message)

Finally, we can make another nice improvement to our server action. By adding a call to Next.js’ revalidatePath function, we can tell the app that some resources need to be reloaded. Said differently, we can refresh the messages displayed on the page after we created the new one:

await postMessage(message)
revalidatePath('/') // assuming the messages are displayed at root

Here is what our form looks like now:

We can see that the message is added to the list without needing to refresh the page. But the form is not reset after being submitted, which can be a little annoying.

Additionally, you probably noticed that the form validation is quite minimalist: we use the HTML validation attributes for the client validation, and a Zod schema for the server one. How nice would it be to use the same validation on both sides?

Good news: it is not because we use server actions that we can’t use cool client features to handle forms. Let’s see how.

Improving the form with client features

So far, our form doesn’t use any client feature. Actually, it is still a server component (that can be used with JavaScript disabled). To add some cool features to it, let’s start by making it a client component.

This means:

adding the 'use client' directive at the top of the file,
moving the server action to a new actions.ts file, as we can’t declare server actions in client files.

To improve our form, I will use the react-hook-form library. Here is how to use it on our form:

export function MessageForm() {
  const { register, handleSubmit } = useForm<MessageFormData>({
    shouldUseNativeValidation: true,
    resolver: zodResolver(formDataSchema),
  })

  return (
    <form onSubmit={handleSubmit((data) => submitMessageForm(data))}>
      <h2>New Message</h2>

      <label htmlFor="name">Your name:</label>
      <input type="text" id="name" {...register('name')} />

      <label htmlFor="content">Your message:</label>
      <textarea id="content" {...register('content')} />

      <button type="submit">Send</button>
    </form>
  )
}

By using register on each field of the form, we let the library handle the form local state and validation. Note that:

we use the existing Zod schema to define the validation rules (thanks to the Zod resolver for react-hook-form),
by setting shouldUseNativeValidation: true, we rely on the browser API to display the validation errors in the form (a feature I love!).

We need to change a bit the server action to comply with the new way data is sent by react-hook-form (a plain object instead of a FormData object):

export async function submitMessageForm(formData: MessageFormData) {
  formDataSchema.parse(formData)
  await postMessage(formData)
  revalidatePath('/')
}

Important note: we may think that because we call the function directly from the form, we don’t have to care about validating the form data (the parameter). We do need to care about it! Although Next.js handles it for us, there is still an HTTP request made to an API endpoint to call the server action. And it is very easy to make this call manually with invalid data.

This is why we still check that the data is conform with the Zod schema at the top of the function, even if TypeScript lets us think the data is already a MessageFormData. But at least, we can use the same validation logic both on the client and the server.

So now we handle the validation a bit better. We can still even improve the form.

First, let’s reset the form after it is submitted. react-hook-form provides a reset function that we can call right after calling the server action (which returns a promise):

export function MessageForm() {
  const {
    // ...
    reset,
  } = useForm<MessageFormData>(/* ... */)

  return (
    <form
      onSubmit={handleSubmit(async (data) => {
        await submitMessageForm(data)
        reset()
      })}
    >

Final improvement: if the submission takes a couple of seconds, it is a good practice to tell the user the form is being submitted, and prevent them from clicking the submit button again. And again, react-hook-form provides the information we need: an isSubmitting flag:

export function MessageForm() {
  const {
    // ...
    formState: { isSubmitting },
  } = useForm<MessageFormData>(/* ... */)

  return (
    {/* ... */}
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? 'Sending…' : 'Send'}
      </button>
    {/* ... */}
  )
}

Now, thanks to client features, we handle validation the same way on the client and the server, we tell the user the form is being submitted, and reset the form when it is done. Tiny improvements but great for the user experience, as well as the developer experience.

Here is how our final guestbook looks like:

To be fair, these last improvements we made come with a cost: it isn’t possible anymore to use the form without having JavaScript enabled. I’ll let you decide whether it is worth it or not.

So, in the end, what do Server Actions offer us, and how do they compare to Server Components?

Server Components let us fetch data without creating an additional endpoint and calling it from the client,
Server Actions let us post data without creating an additional endpoint and calling it from the client.

What I love about server component and actions is that they hide some logic, without making anything magic, and make the code way easier to understand. To me, they even make it easier to learn React, a point of view I developed in my post A better learning path for React with server components.

It’s a bit early to say they will change the way we build web apps on the long term, but I would take that bet!

How to Give Code Review as a Junior Developer?

Sebastien Castiel — Sat, 24 Jun 2023 17:29:06 +0000

“The code must be reviewed by senior developers.” “A review by a junior is nice, but their approval is worth nothing.” If you’ve never heard these phrases, you’re lucky. Of course, they’re completely wrong.

As a junior developer, participating in code reviews offers a valuable learning opportunity and a chance to contribute to the team’s success.

In this post, I’ll explore how you can provide effective code review feedback as a junior developer.

Do you need guidance in your journey as a junior developer? I can help you learn skills, be more confident, and reach your dream job! Check out my mentoring services 😉

Why Code Review?

Code reviews serve several purposes that benefit both individual developers and the team as a whole. Here are a few key reasons why code review is essential:

Learn from the Code

Code reviews expose you to different coding styles, techniques, and approaches. By reviewing code written by other developers, more experienced or not, you can gain valuable insights and enhance your own skills.

Ensure Good Practices

Code reviews help maintain coding standards and best practices within the project. By identifying deviations from established guidelines, you contribute to the overall code quality and maintainability.

For instance, if your team decided that the files should be organized by business modules, and a developer did not follow this convention in their pull-request, then code review is the right way to tell them.

Check for Bugs or Edge Cases

Through careful examination, code reviews help catch potential bugs, logic errors, or vulnerabilities that might have been overlooked during development. Identifying and addressing these issues early on saves time and minimizes future complications.

Note that depending on what your team agreed on, it might or might not be a responsibility of the reviewer to manually test the changes.

Challenge the Implementation

Code reviews encourage critical thinking and provide an opportunity to challenge the design decisions or suggest alternative approaches. By sharing your perspective, even as a junior developer, you contribute to the team’s collective problem-solving capabilities.

What Code Review Should Not Be Used For

While code review is a valuable process, it’s important to understand its scope and limitations. As a junior developer, it’s helpful to know what code review should not be primarily used for:

Code Formatting and Linting

Code reviews are not the place to nitpick about minor formatting or styling preferences. Automated tools and linting processes can handle these concerns, allowing code reviews to focus on more substantial issues: ESLint, Prettier, etc.

Big Architecture Discussion

Code reviews are typically not the ideal place for large-scale architectural discussions. While providing input on architectural decisions can be valuable, it’s better to address these concerns in separate discussions or meetings.

What is Expected from a Junior Developer

As a junior developer participating in code reviews, you have a crucial role to play. Here’s what is expected from you:

Read the Code Carefully and Learn from It

Take the time to thoroughly understand the code being reviewed. Absorb the logic, patterns, and techniques used by more experienced developers, as this will help improve your own skills.

You’ll also learn about the specific project you’re working on, how the application was designed, its technical debt, etc.

Speak Up if Something Isn’t Clear

Don’t hesitate to ask questions or seek clarification if you encounter sections of code that are unclear or confusing. Effective communication ensures everyone is on the same page and helps prevent misunderstandings.

It should be possible for every developer, including junior, to understand every piece of code in the project. If you can’t understand some code, it might be because it wasn’t written in the clearest way.

Note that sometimes, the code is hard to understand for good reasons, for instance to handle performance issues. In that case, comments in the code can be used to make it easier for other developers.

Share Alternative Perspectives

As a junior developer, you bring a fresh perspective to the code review process. If you believe there’s a different, more efficient, or elegant way to implement something, respectfully share your thoughts and encourage discussion.

Don’t think you are not experienced enough to challenge a senior developer’s implementation because you just learned the tech. Sometimes, asking why a developer didn’t follow the practice you just learned leads to insightful discussion!

Use the Right Tone in Your Comments

Providing feedback in a positive and constructive manner is crucial for maintaining a healthy and collaborative team environment. The following tips apply to developers of all levels of experience, but they’re especially relevant for junior developers challenging senior developers’ code.

Use "Why Not" Instead of "You Should"

Frame your suggestions or alternative approaches as questions rather than commands. This approach encourages discussion and allows the developer to explain their thought process.

Example: you notice that a developer did something that the framework’s documentation deprecates. Instead of telling “You should do it this way instead of that way”, consider “I notice the documentation suggest not doing it that way. Why not doing it this way instead?”.

Be Open and Positive

Embrace a supportive tone in your comments, highlighting the positive aspects of the code and recognizing the developer’s effort. By fostering a positive atmosphere, you encourage continuous improvement and inspire your peers.

Example: “I wasn’t aware we could implement the function this way, thanks for helping me learn! Just wondering if it couldn’t cause performance issues, due to…”

If You Think Something is Wrong, Suggest an Alternative

When you add a comment to suggest a change, always try to propose a specific way to make the change. For instance, if you think a variable or function name is wrong (naming things is hard), don’t just tell “Please give a better name to the variable/function”. Instead, you can tell “I think thisName or thatName would make more sense, what do you think?”

As a junior developer, participating in code reviews is an invaluable opportunity to enhance your skills, contribute to code quality, and collaborate effectively with your team.

By approaching code review with a desire to learn, sharing constructive feedback, and fostering a positive environment, you can make a meaningful impact on the development process.

Embrace code reviews as a chance to grow and improve, both individually and as part of a team.

Cover photo by Annie Spratt.

How well should I know React before applying to my first job?

Sebastien Castiel — Sun, 18 Jun 2023 14:53:06 +0000

A recurring question I hear from people learning React: “how do I know if I’m ready to apply to junior React developer jobs?”. Very often, they’re ready before they know.

If you’ve built a couple of applications using React (your portfolio, a side project…), I bet you’re ready! (If you haven’t, what not checking out my React workshop? 😇)

In this article, I listed some things you don’t have to know, and some you do. My goal is to prepare you to your first technical interview.

Let’s start with what you think you might need to know but definitely don’t.

You don’t have to know everything

It’s okay not to know how React works internally

React is complex, and not many developers know how it works internally. Although it’s a fascinating topic, don’t feel you have to learn it unless you want to apply at Meta to work on React.

It’s okay not to have dozens of projects with React

Showing you worked on a couple projects is more than enough. The more different they are, the better, especially if you’re able to tell how they were different and how it made the challenges different too.

It’s okay not to have built a huge project with React

Of course, if you worked on a big project, it’s an advantage. But don’t do it just to increase your chances at your first job interview, it isn’t worth it. If you get the job, you might work on a big project you’ll tell about at the interview for your next job!

It’s okay not to know how to bootstrap a complex React app

Do you know how to bootstrap an app with the right npm or yarn command? It’s enough! Actually, looking for it in the documentation is enough. Bootstraping an entreprise app is a useless skill, as only one person will do it in any project, and will probably forget about it before the next project.

It’s okay not to know how to set up a deployment pipeline for React

Setting up a deployment pipeline is not something expected from a junior developer. Plus, all applications are different, and a pipeline at one company might differ from the one at another company.

It’s okay not to know Redux/Xstate/Tailwind/Next.js…

It may be seen as an advantage to have used an external library in a React project, but there’s a huge chance that the one you learned is not the one used where you’re applying. So don’t overthink it too much.

It’s okay to go find answers on the web

Senior developers go find answers on Google, StackOverflow or ChatGPT all the time! No one will expect you to know how to build an application without using resources you can find on the web.

Alhought it’s okay to go on the web to find some information, example, answers, there are basics you should know very well before going to your first technical interview:

But there are some things you should know

Know JavaScript

I know it isn’t technically React, but if you don’t master JavaScript’s basics during the interview, it isn’t a good start. Know how to declare constants, functions, how to use the spread syntax to update arrays and objects, or how to use promises…

Know how to create a component

You should know how to create a new component (as a function) with basic HTML content, and display it in your browser.

Know how to display data conditionnaly, and how to perform iterations

Be prepared to use the ternary operator ? : to display data depending on a condition, and to use .map to display several elements from an array (and don’t forget to use the key prop).

Know how to add a local state to the component

useState is the most useful hook, and you should know how to use it: how to declare a state, how to update it, how to deal with complex states such as arrays or objects…

Know how to add some form inputs in it

Dealing with a text input is something you’ll have to do in many apps. Better be able to show you can do it without leaving your IDE.

Know how to update the state when the user types something

Displaying an input is nice, but you should also know how to use the change event to update the state accordingly.

Know how to perform a fetch request when the component is loaded

Maybe you won’t have to use fetch, but you should at least know how to call an async function in the component… well, in a useEffect, without forgetting to define the dependency array.

Know how to update the state depending on the fetch request result

Storing the result of an async request (using a combination of useState and useEffect) is a very common pattern. If you show you can do it eyes closed, the recruiter will be impressed!

Know how to extract some logic in another component, passing props

Components are at the core of React, so you should know how to create a new component accepting props, and use it in the one you already created.

Know what you don’t know

Even if you don’t know how to use them, be able to mention the other hooks that exist and what they can be used for: useReducer, useRef… You can also read about server-side rendering, global state management libraries such as Redux…

Do you feel more confident now? Even if you don’t know some of the points I mentioned, you must admit it’s not that much: if you learned React already, you shouldn’t need too much time to learn what you’re missing.

Also, it’s okay if you don’t do perfectly well during the interview. The most important is that you don’t feel blocked. If you do, tell the interviewers and they’ll unblock you.

Hopefully you feel more prepared now; or at least you know what to prepare next 😊.

If you need any help to get ready for your first (or next) job interview, have a look at the mentoring services I’m offering! I can help by answering questions, reviewing your portfolio, and even make you pass a mock interview 😉.

Cover photo by Lautaro Andreani.

A better learning path for React with server components

Sebastien Castiel — Wed, 14 Jun 2023 13:27:45 +0000

I’ve always loved sharing my knowledge. When I love a language, library or framework, more than exploring every tiny detail of it, I think about how I can help people learn it and like it as much as I do.

This is why a while ago I wrote a book in French about React, then a course about React hooks, and finally an ebook about Next.js last fall (see my books page).

But the world of programming is evolving fast, and the recent new features in React and Next.js shuffle everything. Not in a way that everything you know already is now wrong, but because you can do much more than before, and learn things completely differently.

With the recently-introduced React Server Components (RSC), it is now possible to create components that will be rendered on the server. My goal here is not to explain how to use them or what new features they bring, but to propose a new way of learning React they enable.

PS: I am now offering a workshop called Learn React the Modern Way teaching React the way I propose here. There is also an online course if you prefer 😉.

Here is the way we use to teach/learn React and Next.js:

Start with React’s client features to build a Single Page Application: local state, effects…
Continue with Next.js to create full-stack apps, with Server-Side Rendering
Pursue with React Server Components to add more logic on the backend

This is how most people went from client-only React to RSC, because Next.js was created after React, and RSC only became real a few months ago.

What if we took advantage of React Server Components not only to improve how we use React, but also how we help people learn it from the beginning?

Think about it. Why not starting with React Server Components, then moving to client features?

It could look like this:

Learn Next.js as a full-stack framework, using React as a rendering engine
Discover React’s client features to add interactivity to your pages

In the first part of the journey, you could learn how to create React components on the server, and fetching data directly from inside the component.

export default async PostsPage() {
  const posts = await fetchPosts()

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

If you aren’t used to React Server Components, this piece of code might seem weird. But for someone who doesn’t know React yet, the logic is quite easy to understand. You fetch posts, then you display them.

Using a plain client component, you’d have to create a state with useState, then fetch the posts inside a useEffect. Explaining everything you need to understand the code would take much longer.

And don’t get me wrong: it’s important to know how to perform a request from a client component. Just, maybe a bit later, when you learn React’s client features. But you can already learn so much without hearing the word “hook”: components, JSX, conditionals & iterations, styling, routing, fetching data…

I understand this path I’m proposing can seem counter-intuitive. And to be honest, it’s still a bit early to know for sure whether it’s better than the classic way. I am glad to see that I’m not the only one thinking it might be:

I just finished designing a workshop called Learn React the Modern Way to help beginners learn React and Next.js, and will experiment this new path. I strongly believe it will make the learning journey way easier for people who know HTML, CSS and JavaScript.

Can’t wait to keep you posted about how it goes 😊

Cover photo by Matt Duncan.

Create OG images for your blog with Next.js

Sebastien Castiel — Thu, 10 Nov 2022 15:17:18 +0000

At the same time I released the new design for this blog using Next.js, Vercel announced a new library to generate OpenGraph (OG) images. You know, these images you can see when posting some links on Twitter.

Since my blog posts had a cover image associated, it sounded natural to me to use this image. But I often wonder if it was worth it to generate an image with additional content such as the post title or its date. It was pretty complicated to generate an image.

Fortunately, Vercel’s OG library now makes it much easier. Let’s see how by implementing OG image generation for an imaginary blog.

👉 If you are curious about Next.js and want to learn it, check out by book Serverless Web Applications with React and Next.js.

📺 If you prefer video content, I created a short video with the content of this post:

`@vercel/og`, `satori`, and Edge functions

Generating OG images is made possible by the @vercel/og library, itself relying on satori (also made by Vercel). This package allows you to create an image from HTML and CSS code (using JSX). @vercel/og adds a layer to make it easier to use, for instance by loading a default font so you don’t have to.

On the client, such generation does not sound complicated, and we’ve known how to do it for a long time using a canvas element. But on the server, you had to start a headless Chrome browser, which was complex and expensive. satori doesn’t work that way, and can generate images efficiently on the client, or in serverless functions.

Even better, it can run on Edge functions, and that is what @vercel/og does. Edge functions are a special kind of serverless functions, that are free from all the classic Node.js runtime features. You can only use the basic JavaScript features, from the V8 runtime, so Edge functions comes with some limitations, but are extremely fast, and their execution cheaper.

Generate an image with `@vercel/og`

You can follow this tutorial on any Next.js project. I’ll show how to start from an empty Next.js application, just generated with the command:

$ yarn create next-app hello-og --typescript

In this project, we’ll use a serverless function to generate OG images, accessible at the endpoint /api/og. Let’s create it in a new /pages/api/og.tsx file.

import { NextRequest, NextResponse } from 'next/server'

export const config = {
  runtime: 'experimental-edge',
}

const handle = (req: NextRequest) => {
  return NextResponse.json({ hello: true })
}

export default handle

If you are used to serverless functions in Next.js, you might notice some differences:

The exported config object. Here we tell Next.js that this function is an Edge function.
The req parameter does not have the NextApiRequest type, but NextRequest. This is also because it’s an Edge function.
We return a response (instead of using a res object passed as parameter), of type NextResponse.

Still, if you run the application and call the endpoint, you will get the expected JSON result, as with any classic function:

$ curl http://localhost:3000/api/og
{"hello":true}

Now let’s update this function to return an image using @vercel/og. We first need to add the dependency to our project with yarn add @vercel/og. Then we can generate a basic image containing the text “Hello World!”:

import { ImageResponse } from '@vercel/og'
// ...

const handle = (req: NextRequest) => {
  return new ImageResponse(
    <div>Hello World!</div>,
    // 1200x628 seems to be the right dimensions to use for OG images.
    { width: 1200, height: 628 },
  )
}

With these three lines of code returning an ImageResponse, we generate an image from React code. That sounds easy, right? You probably think “this is great, I can use all my React components!”… Well, it’s not that easy 😉.

Even though we use JSX here, it’s important to understand that it’s just a shorthand offered by satori (which seems to use React, but not React-DOM). The JSX code you write here has some constraints:

Not all CSS properties are supported,
Only flex layout is supported, and each element with multiple children must explicitely use (display: flex),
You can’t use script or link elements, etc.

Knowing these constraints, we can still do a lot. A feature I love: you can use TailwindCSS classes natively, using the tw prop on elements (instead of className). If you prefer, you can use the classic style prop to specify CSS properties.

Let’s assume we want to display a post title, an author name, and a date that we’ll receive from query parameters. To get these parameters, we can’t use req.query: in Edge functions, we have to use req.url, that we can parse using the URL class:

const handle = (req: NextRequest) => {
  const { searchParams } = new URL(req.url)
  const title = searchParams.get('title') || 'No post title'
  const author = searchParams.get('author') || 'Anonymous'
  const date = new Date(searchParams.get('date') || '2022-11-05T12:00:00.000Z')

And then, we can use these parameters to add them to the image, with some TailwindCSS classes to make everything a bit more beautiful:

  return new ImageResponse(
    (
      <div tw="flex w-full h-full flex-col justify-end bg-slate-200 items-stretch">
        <div tw="flex flex-col bg-white p-8">
          <div tw="text-5xl mb-4">{title}</div>
          <div tw="text-2xl">
            {author +
              ' – ' +
              date.toLocaleDateString('en-US', { dateStyle: 'long' })}
          </div>
        </div>
      </div>
    ),
    { width: 1200, height: 628 }
  )
}

Here is what this first version of our OG image looks like, with some parameters:

An image inside the image

This is nice, but it misses the most important thing we want on it: the cover image. Let’s add a cover parameter, and use it in an img element:

const handle = (req: NextRequest) => {
  const { searchParams, host, protocol } = new URL(req.url)
  // ...
  const cover = `${protocol}//${host}${
    searchParams.get('cover') || '/cover.jpg'
  }`

  return new ImageResponse(
    (
      <div tw="flex w-full h-full flex-col justify-end bg-slate-200 items-stretch">
        <img
          src={cover}
          alt=""
          tw="flex-1 w-full h-full"
          style={{ objectFit: 'cover', objectPosition: 'center' }}
        />
        {/* ... */}
      </div>
    ),
    { width: 1200, height: 628 }
  )
}

(To run the example, go get an image on Unsplash and put it in public/cover.jpg.)

Note how we use the host and protocol attributes from the request’s URL, as we need to use absolute URLs for img elements.

This second version is much more satisfying 😊… until we deploy it on Vercel. After deployment, if you call try to generate an image, you might get a blank image. In the Vercel logs, you’ll see this kind of error:

It isn’t obvious, but the issue comes from the cover image we want to include, which seems too big for @vercel/og at the time I’m writing this post. We could choose to use a smaller image, but it’s pretty annoying…

Good news, Next.js already provides an easy way to resize images. When using the next/image component, Next.js uses an endpoint at /_next/image. While we can not use the component, we can use the endpoint!

const cover = `${protocol}//${host}/_next/image?url=${encodeURIComponent(
  searchParams.get('cover') || '/cover.jpg'
)}&w=1200&q=75`

Add OG image to your pages

Now that we know how to generate our image, we can use it in the meta tags of the page headers. You can find the complete list of meta tags you need to define in Twitter documentation. I like using a custom component I built in many projects of mine: SeoHeaders.

If you are adding OG images to a Next.js blog, I assume you already have a component in which you know the post title, author, date, and cover image. You can build the OG image URL:

// It must be an absolute URL, so I use an
// environment variable for the base URL.
const imageUrl =
  `${process.env.NEXT_PUBLIC_BASE_URL}/api/og?` +
  `title=${encodeURIComponent(title)}` +
  `&author=${encodeURIComponent(author)}` +
  `&cover=${encodeURIComponent(cover)}` +
  `&date=${date}`

Then, you can pass this URL to the SeoHeaders component:

<SeoHeaders
  title={title}
  description=""
  author={author}
  twitterAuthor=""
  twitterSite=""
  url={process.env.NEXT_PUBLIC_BASE_URL}
  imageUrl={imageUrl}
/>

Or, if you add the meta tags by yourself:

<meta property="og:image" content={imageUrl} />
<meta name="twitter:image" content={imageUrl} />

Note that so that the image is used in social media, you need to specify the other tags: og:type, twitter:card, etc.

This concludes this tutorial about generating and using OG images in a Next.js application! Our image is pretty minimalist, but here are a few ideas if you want to improve it:

Play with opacity options (using TailwindCSS class bg-opacity-50 for instance) instead of having a white background for the text.
Add the author’s avatar (using a second image).
Add the description to the image, or an excerpt of it.
If your blog allows comments or likes, you can add some counter to the image.

You’ll find the complete source code of the example Next.js application on this GitHub repo. Don’t forget to check out the documentation of Vercel’s OG Image Generation.

This post was first posted on my blog: Create OG images for your blog with Next.js.

Cover photo by Noman Shahid.

Combining scripts and DSLs is Kotlin’s most underrated feature

Sebastien Castiel — Thu, 24 Mar 2022 20:51:07 +0000

I discovered Kotlin recently and realized that, for many people, it was only a new syntax for Java. But the more I play with it, the more convinced I am that a combo of two of its features is vastly underrated:

The ability to create domain-specific languages (DSL), thanks to some syntactic sugar;
The ability to write scripts and create interpreters for them.

You can easily guess how nice these features can play together. We can create a DSL, tailor it to our needs, and use it in scripts. Why scripts? Let me introduce the example I will develop here to illustrate why.

Not long ago, I started keeping track of my personal finances. I wanted to keep track of the total value of everything I own (money in bank accounts, stocks, real estate), and I was disappointed in the third-party services I found. So I developed my own tool to fit my needs. (Want to know more? I wrote a book about it!)

My program’s input had to be the values of my accounts over time (I wanted to manually write each value instead of relying on an unreliable API to fetch them automatically). To provide this input, I had quite a few options:

I could store them in a database and develop tools to populate it (a GUI, a CLI…)
I could put them in a JSON file
Why not store them in a Kotlin file?

Providing the input in a Kotlin file sounded like a weird thing to do. On the one hand, I could benefit from IntelliJ’s autocomplete features since I would use the functions and classes I wrote. On the other hand, it meant I would have to rebuild the program each time I updated the input?? How unpractical does it seem?

Here is where scripts come into play. With Kotlin, you can write a script interpreter embedding your domain logic, including a DSL, and write scripts providing the input to that logic.

In this article, we’ll build a “minimum viable example”, a net worth tracker to demonstrate how it can work. But if you already know Kotlin, you likely already use scripts and DSLs without even knowing it: in your build.gradle.kts file, you are using the Gradle DSL in a script!

The full example is available on GitHub. The main branch contains the final version, and you’ll find there two branches step-1 and step-2 with the code of the first two sections. I removed the imports from the code examples to make the post lighter, but you can follow the link attached to code blocks to see the full file content.

Step 1: Create the domain logic

We want to write a program that takes accounts and snapshots as inputs and displays a report as an output. A snapshot represents the states of several accounts at a given date, so the class contains a date attribute and a mapping between accounts and their respective value.

// https://tinyurl.com/yckwfds4
data class Account(val id: String, val name: String)

// https://tinyurl.com/57vr36mw
data class Snapshot(val date: LocalDate, val balances: Map<Account, Double>)

To create a report, we need to provide a list of accounts and snapshots. Our minimal report will have two features: displaying the account list and displaying each snapshot (with, for each of them, the value of each account).

// https://tinyurl.com/2whmpup6
class Report(val accounts: List<Account>, val snapshots: List<Snapshot>) {
  fun displayAccountList() {
    println("ACCOUNTS:")
    accounts.forEach { println("- ${it.name}") }
  }

  fun displaySnapshots() {
    println("SNAPSHOTS:")
    snapshots.forEach { snapshot ->
      println("* ${snapshot.date}:")
      accounts.forEach { account ->
        println("  - ${account.name}: ${snapshot.balances[account]?.toString() ?: "-"}")
      }
    }
  }
}

As a first step, let’s use these classes in the main function. We first create two accounts, then two snapshots defining a value for these accounts. Finally, we create a report and display the accounts’ and the snapshots’ list.

// https://tinyurl.com/s8564hy5
fun main(args: Array<String>) {
  val checking = Account("checking", "Checking")
  val savings = Account("savings", "Savings")

  val snapshots = listOf(
    Snapshot(
      LocalDate.parse("2022-01-01"),
      mapOf(checking to 1000.0, savings to 2000.0)
    ),
    Snapshot(
      LocalDate.parse("2022-02-01"),
      mapOf(checking to 1200.0, savings to 2500.0)
    )
  )

  val report = Report(listOf(checking, savings), snapshots)
  report.displayAccountList()
  report.displaySnapshots()
}

Ok, our program works, but we will improve it in two ways: first, we will make it possible to extract the content of main into a script (so we don’t have to rebuild the application when we add new snapshots), then we will create some helpers (our DSL) to make it easier to edit the script.

Step 2: Create a script definition

Using Kotlin to write scripts is unfortunately not a very well-documented feature. It changed a lot in the past, so the tutorials you can find are not always still valid. But it doesn’t mean we cannot enjoy it!

The first step is to include some dependencies to our project:

// https://tinyurl.com/5ase8sdr
dependencies {
  // ...
  implementation("org.jetbrains.kotlin:kotlin-scripting-common:1.6.0")
  implementation("org.jetbrains.kotlin:kotlin-scripting-jvm:1.6.0")
  implementation("org.jetbrains.kotlin:kotlin-scripting-jvm-host:1.6.0")
}

To be able to write a script interpreter, we need to create two entities: a script definition and a script host. Let’s start with the script definition, NwtScript (nwt stands for net worth tracker). It can be as simple as an abstract class annotated with @KotlinScript. To make writing script easier, we can also provide some classes that will automatically be imported, using a ScriptCompilationConfiguration object:

// https://tinyurl.com/yc26svyp
@KotlinScript(
  fileExtension = "nwt.kts",
  compilationConfiguration = NwtScriptConfiguration::class
)
abstract class NwtScript

object NwtScriptConfiguration: ScriptCompilationConfiguration({
  defaultImports(Account::class, Snapshot::class, Report::class, LocalDate::class)
})

We also provide an extension for our scripts; note that, so we enjoy IntelliJ’s features such as autocomplete, this extension has to be composed of a prefix of your choice, then .kts.

We can now create the script host NwtScriptHost to use this script definition. This class has nothing very complex: it has a public execFile method that accepts a filename, evaluates it using a BasicJvmScriptingHost, and displays possible log messages.

// https://tinyurl.com/2p88u9a5
class NwtScriptHost {
  private fun evalFile(scriptFile: File): ResultWithDiagnostics<EvaluationResult> {
    val compilationConfiguration = createJvmCompilationConfigurationFromTemplate<NwtScript> {
      jvm {
        // Script will have access to everything in the classpath
        dependenciesFromCurrentContext(wholeClasspath = true)
      }
    }
    return BasicJvmScriptingHost().eval(scriptFile.toScriptSource(), compilationConfiguration, null)
  }

  fun execFile(path: String) {
    val scriptFile = File(path)
    val res = evalFile(scriptFile)

    res.reports.forEach {
      if (it.severity > ScriptDiagnostic.Severity.DEBUG) {
        println(" : ${it.message}" + if (it.exception == null) "" else ": ${it.exception}")
      }
    }
  }
}

As the final step before we create our script, we need to tell IntelliJ about our script definition, so it knows what classes we can access and provide the autocomplete and code annotation features we like.

We need to create a folder src/main/resources/META-INF/kotlin/script/templates and in it an empty file named nwt.script.NwtScript.classname (the full class name + .classname). Here is the part I’m least comfortable explaining because I found how to make it work on some forums and not in official documentation 😅.

After creating the file, rebuild the application, and you may need to restart IntelliJ, invalidate caches… To be honest, I’m not sure exactly what works, but in the end, when you create a .nwt.kts file (let’s say my.nwt.kts at the project’s root), IntelliJ should tell you there is a script definition available for it 🎉.

Put the content of main in the new script file, and if everything went well, you should see that IntelliJ annotates the parameters of Account, for instance:

// https://tinyurl.com/4enfpevm
val checking = Account("checking", "Checking")
val savings = Account("savings", "Savings")

val snapshotJanuary = Snapshot(
  LocalDate.parse("2022-01-01"),
  mapOf(checking to 1000.0, savings to 2000.0)
)
val snapshotFebruary = Snapshot(
  LocalDate.parse("2022-02-01"),
  mapOf(checking to 1200.0, savings to 2500.0)
)

val report = Report(
  listOf(checking, savings),
  listOf(snapshotJanuary, snapshotFebruary)
)
report.displayAccountList()
report.displaySnapshots()

To transform our program into an interpreter for our script, we can now update our main function:

// https://tinyurl.com/mpzhf66e
fun main(vararg args: String) {
  if (args.size != 1) {
    println("usage: <app> <script file>")
  } else {
    NwtScriptHost().execFile(args[0])
  }
}

To run it, we can update the project’s run configuration, defining “my.nwt.kts” in the Program arguments field. You will notice that the application won't be rebuilt if you update the script file and rerun it!

It is already lovely, but we can make our script better by providing high-level functions, so we don’t feel like writing code!

Step 3: Create builders and the DSL

We will use a well-known design pattern to implement our DSL: the Builder pattern. For instance, to create a Snapshot, we can create a class SnapshotBuilder. Its constructor takes two parameters: the snapshot’s date and a map of accounts (we will see later how we provide these accounts).

// https://tinyurl.com/4tuffu26
class SnapshotBuilder(val date: LocalDate, val accounts: Map<String, Account>) {
  private val balances: MutableMap<Account, Double> = mutableMapOf()

  fun balance(accountId: String, amount: Double) {
    val account = accounts[accountId] ?: throw Exception("Invalid account ID")
    balances[account] = amount
  }

  fun build(): Snapshot {
    return Snapshot(date, balances)
  }
}

To use the builder, we can call its balance method to define the accounts’ balances; then, we call the build method to get the snapshot.

val builder = SnapshotBuilder(LocalDate.parse("2022-01-01"), accounts)
builder.balance("checking", 1000.0)
builder.balance("savings", 2000.0)
val snapshot = builder.build()

But we can do better. We can define a snapshot function taking two parameters:

date: the snapshot’s date,
initialize: a function to initialize the builder. This function will receive the builder as this (thanks to the call to apply), meaning that we will be able to call the balance method without any prefix.

fun snapshot(val date: String, initialize: SnapshotBuilder.() -> Unit): Snapshot {
  // We’ll see soon where `accounts` comes from
  return SnapshotBuilder(LocalDate.parse(date), accounts).apply(initialize).build()
}

val snapshot = snapshot("2022-02-01") {
  balance("checking", 1000.0)
  balance("savings", 2000.0)
}

To me, this is what makes Kotlin great for writing DSLs. When using the snapshot function, you don’t realize you are creating and using a builder!

Let’s create another builder to build several snapshots as a next step. This new SnapshotsBuilder will use the SnapshotBuilder and embed the snapshot we just saw (renaming it on for a better DSL, you’ll see):

// https://tinyurl.com/52fbfhhn
class SnapshotsBuilder(val accounts: Map<String, Account>) {
  private val snapshots: MutableList<Snapshot> = mutableListOf()

  fun on(date: String, initialize: SnapshotBuilder.() -> Unit) {
    val snapshotBuilder = SnapshotBuilder(LocalDate.parse(date), accounts).apply(initialize)
    snapshots.add(snapshotBuilder.build())
  }

  fun build(): List<Snapshot> {
    return snapshots
  }
}

We will use this builder via another function, snapshots:

fun snapshots(initialize: SnapshotsBuilder.() -> Unit) {
  // We’ll see soon where `accounts` comes from
  snapshots.addAll(SnapshotsBuilder(accounts).apply(initialize).build())
}

snapshots {
  on("2022-01-01") {
    balance("checking", 1000.0)
    balance("savings", 2000.0)
  }
  on("2022-02-01") {
    balance("checking", 1200.0)
    balance("savings", 2500.0)
  }
}

Let’s continue by creating a builder for reports. The ReportBuilder class technically doesn’t implement the builder pattern since it doesn’t build anything (and doesn’t have a build method), but it will still be helpful to us:

// https://tinyurl.com/2v35d9fu
class ReportBuilder(val accounts: List<Account>, val snapshots: List<Snapshot>) {
  private val report = Report(accounts, snapshots)

  fun accounts() {
    report.displayAccountList()
  }

  fun snapshots() {
    report.displaySnapshots()
  }
}

Same as we did for snapshots, we can create a report function.

fun report(initialize: ReportBuilder.() -> Unit) {
  // We’ll see soon where `accounts` and `snapshots` come from
  ReportBuilder(accounts.values.toList(), snapshots).apply(initialize)
}

report {
  accounts()
  snapshots()
}

Last but not least, let’s create the last builder to unify them all! Our NwtBuilder embeds the snapshots and report functions as methods and is responsible for keeping the state of our program: the accounts and the snapshots:

// https://tinyurl.com/2p8n8av6
class NwtBuilder {
  private val accounts: MutableMap<String, Account> = mutableMapOf()
  private val snapshots: MutableList<Snapshot> = mutableListOf()

  fun account(id: String, name: String) {
    accounts[id] = Account(id, name)
  }

  fun snapshots(initialize: SnapshotsBuilder.() -> Unit) {
    snapshots.addAll(SnapshotsBuilder(accounts).apply(initialize).build())
  }

  fun report(initialize: ReportBuilder.() -> Unit) {
    ReportBuilder(accounts.values.toList(), snapshots).apply(initialize)
  }
}

// https://tinyurl.com/3cue36re
fun nwt(initialize: NwtBuilder.() -> Unit) {
  NwtBuilder().apply(initialize)
}

With the new nwt function, we won’t need access to the classes Account, Snapshot, and Report in the script. So we can update the script definition:

// https://tinyurl.com/mhecyc6n
@KotlinScript(fileExtension = "nwt.kts", compilationConfiguration = NwtScriptConfiguration::class)
abstract class NwtScript

object NwtScriptConfiguration: ScriptCompilationConfiguration({
  // give access to our `nwt` function without importing it
  defaultImports("nwt.dsl.nwt")
})

Now we have everything we need to update our script. No more val, no more explicit object creation. Only the bare minimum to provide to the interpreter the inputs (the accounts and their balances over time) and what we want as output (the report definition).

// https://tinyurl.com/3xh24mny
nwt {
  account("checking", "Checking")
  account("savings", "Savings")

  snapshots {
    on("2022-01-01") {
      balance("checking", 1000.0)
      balance("savings", 2000.0)
    }
    on("2022-02-01") {
      balance("checking", 1200.0)
      balance("savings", 2500.0)
    }
  }

  report {
    accounts()
    snapshots()
  }
}

Again, since we updated the script definition, you may need to rebuild the project, invalidate caches, restart IntelliJ, etc., to make it effective. But look at how nice it is that IntelliJ recognizes our DSL:

Kotlin is already widely used to write domain-specific languages. You can use it to write Gradle configuration files, to create HTML documents, and I hope I convided you that creating your own DSL is worth it too, especially used in combination with the ability to write script interpreters.

Custom React hooks to use the browser’s APIs

Sebastien Castiel — Mon, 18 Jan 2021 14:23:11 +0000

A thing you often need to do in React is access the browser’s APIs. These APIs represent side effects, and most of the time, you will want to store what they return in a local state: a perfect opportunity to write some custom hooks that you’ll be able to reuse across your applications.

Access the local storage

The browser’s local storage is a place you can save some values, so they are persisted for when you leave the page and go back. It’s key-value storage and its API is quite straightforward:

// returns null if no value exists for the given key
const value = localStorage.getItem('key')
localStorage.setItem('key', 'value')

If you are not familiar with it, you can play with it just by using the console in your browser. Try to create some values, refresh the page, and get them back. Note that you can only store string values.

Here, we’ll write an improved version of the useState hook that persists the value in the local storage. If the user refreshes the page, the state will be initialized with the stored value.

We want our hook to be used almost the same way as useState, so we will make it return the same kind of array, with the current value and a setter. It will accept as parameters the initial state value and the key used to store the value in the local storage.

Let’s start by just using a classic state provided by useState:

const usePersistedState = (key, initialValue) => {
  const [value, setValue] = useState(initialValue)
  return [value, setValue]
}

First thing, when setting a new value, we want to store this new value in the local storage using localStorage.setItem. Let’s create a function doing this operation just after calling the original setValue, and return this function in place of setValue:

const setAndPersistValue = (newValue) => {
  setValue(newValue)
  localStorage.setItem(key, newValue)
}

return [value, setAndPersistValue]

Then, when the component is mounted, we want to get the currently stored value from the state, and if it exists, update our state’s value with it.

At that point, we have a choice to make: what value do we want to return before we get the value from the local storage? Two solutions:

We return the provided initialValue and replace it with the existing value if it exists;
We return null or undefined, then the current value if it exists, the provided initialValue otherwise.

There is no absolute best choice here; it depends on your need. But if you intend to distribute this hook to other people, your documentation should mention the choice you made.

Here I chose the first way to do it and kept using the initialValue.

const [value, setValue] = useState(initialValue)

useEffect(() => {
  const existingValue = localStorage.getItem(key)
  if (existingValue !== null) {
    setValue(existingValue)
  }
}, [key])

Here is how you can do the other way:

const [value, setValue] = useState(null)

useEffect(() => {
  const existingValue = localStorage.getItem(key)
  if (existingValue !== null) {
    setValue(existingValue)
  } else {
    setValue(initialValue)
  }
}, [key])

Our hook is complete, let’s see how to use it. We’ll create a component with an input, and use our hook to persist the value entered in the input in the local storage:

const Comp = () => {
  const [name, setName] = usePersistedState('name', 'John Doe')
  return (
    <input
      type="text"
      value={name}
      onChange={(event) => setName(event.target.value)}
    />
  )
}

Don’t you find it pleasant to use our custom hook almost the same way we would use useState? And that we hid in our hook most of the complexity to access the local storage so the developers using it won’t even be aware of it?

Get an element’s size

Another thing you might want to do is adapt your component's behavior depending on some element size. What would be cool is having a hook returning me the current width and height of any element I want in realtime. Let’s see how we can create such a hook.

First, let’s put React aside for a minute and see how to get the size of a DOM element using plain JavaScript. Modern browsers offer an object ResizeObserver that we can use for that. Its API is not the easiest to apprehend at first sight; for our use case, it consists in:

Creating an instance of ResizeObserver, passing it a callback executed each time one of the observed elements’ size has changed;
Subscribe to observe each element we want to.

Here is an example displaying in the console the width and height of an element each time it is modified:

const element = document.querySelector('#myElement')

// 1.
const resizeObserver = new ResizeObserver((entries) => {
  for (let entry of entries) {
    if (entry.contentRect) {
      console.log(entry.contentRect.width, entry.contentRect.height)
    }
  }
})

// 2.
resizeObserver.observe(element)

Note that we loop through several entries in the callback given to RedizeObserver; this is because an observer can observe several elements, although we will only observe one here.

Let’s come back to React: to know the size of a DOM element, we need first to get this element. We will need to use a ref, via the useRef hook. We saw how refs were useful in a previous lesson when dealing with async code; here is another common use case.

By creating a ref with useRef and passing it as the ref prop of any HTML element rendered in your component, you can access the DOM element itself via yourRef.current:

const inputRef = useRef()

useEffect(() => {
  console.log(inputRef.current.value)
  // logs “Hello!”
}, [inputRef])

return <input ref={inputRef} defaultValue="Hello" />

Here we need this ref to observe it via our ResizeObserver, so we will pass it as a parameter to our custom hook. Here is how we expect to use our hook; let’s name it useElementSize:

const Comp = () => {
  const divRef = useRef()
  const [width, height] = useElementSize(divRef)

  return (
    <div
      style={{
        // Initial size
        width: 150, height: 100,
        // Makes the element resizeable
        resize: 'both', overflow: 'auto',
        // So it’s easier to resize
        border: '1px solid #191a21',
      }}
      ref={divRef}
    >
      {width}x{height}
    </div>
  )
}

As you can see, we want our hook to return the width and height of the element pointed by the ref, and of course, we want these values to be updated when the user resized the element.

So our hook useElementSize has to keep the current element’s width and height in a local state, and returns them:

const useElementSize = (elementRef) => {
  const [width, setWidth] = useState(undefined)
  const [height, setHeight] = useState(undefined)
  // ...
  return [width, height]
}

The last missing piece is to create the ResizeObserver to update these local state values when the element is resized:

useEffect(() => {
  const resizeObserver = new ResizeObserver((entries) => {
    for (let entry of entries) {
      if (entry.contentRect) {
        setWidth(entry.contentRect.width)
        setHeight(entry.contentRect.height)
      }
    }
  })
  resizeObserver.observe(elementRef.current)

  // Let’s disconnect the observer on unmount:
  return () => { resizeObserver.disconnect() }
}, [elementRef])

Notice that we subscribe to the observer in a useEffect and that we disconnect the observer when the component is unmounted.

Get the user’s geolocation

To conclude this lesson, let’s see another example of the browser’s API, which you can access very elegantly via a custom hook: the geolocation API. As its name suggests, the idea is to get the user’s location, meaning the latitude and longitude of their position. Of course, this API can be used only on devices supporting it (mobile devices, modern browsers) and only if the user agreed to be geolocated.

You can access this API using the navigator.geolocation object, more precisely its method getCurrentPosition. It accepts two callback parameters: one executed when the browser successfully returns the current position, the other when an error occurred, meaning the device does not support geolocation or the user didn’t authorize the page to get it.

navigator.geolocation.getCurrentPosition(
  (res) => console.log(res.coords.latitude, res.coords.longitude),
  (err) => console.log('Impossible to get current position')
)

To return the user’s current position via a custom hook, we will apply the same pattern we used in the previous two examples:

Keep a local state with the position.
Call the geolocation API in a useEffect to update the state.
Return its values.

We’ll introduce a small difference, though: since we want to handle the error case, we will also return a status attribute indicating if we are waiting for the position ('pending'), if we fetched it successfully ('success'), or if an error occurred ('error').

const useGeolocation = () => {
  const [status, setStatus] = useState('pending')
  const [latitude, setLatitude] = useState(undefined)
  const [longitude, setLongitude] = useState(undefined)

  useEffect(() => {
    navigator.geolocation.getCurrentPosition(
      (res) => {
        setStatus('success')
        setLatitude(res.coords.latitude)
        setLongitude(res.coords.longitude)
      },
      (err) => {
        console.log(err)
        setStatus('error')
      }
    )
  }, [])

  return { status, latitude, longitude }
}

In the components using this hook, we can then use the returned status attribute to decide what to display:

export const Comp = () => {
  const { status, latitude, longitude } = useGeolocation()

  switch (status) {
    case 'pending':
      return <p>Waiting for geolocation…</p>
    case 'success':
      return (
        <p>Your location: ({latitude}, {longitude})</p>
      )
    case 'error':
      return <p>Have you authorized me to access your geolocation?</p>
  }
}

With these three custom hooks examples to use the browser’s APIs, you probably notice that the recipe is very similar. With this in mind, you are now able to write many custom hooks. It doesn’t mean that they will solve every problem, but they are an additional tool you can use to make your code cleaner, especially when you want to access features provided by the browser.

What are your favorite custom hooks?

If you liked this post, I talk a lot more about React and hooks in my new course useEffect.dev. Its goal is to help you understand how they work, how to debug them, and how to solve common problems they can cause.

You can also follow me on Twitter (@scastiel), where I regularly post about React, hooks, frontend in general, and other subjects 😉

DEV Community: Sebastien Castiel

[Boost]

Seven Hours, Zero Internet, and Local AI Coding at 40,000 Feet

Seven Hours, Zero Internet, and Local AI Coding at 40,000 Feet

What I Threw Together Before Takeoff

Seven Hours at 40,000 Feet

The Broader Reality Check

What This Actually Means

Back to Reality

Turning Claude Code Into My Best Design Partner

When Simple Doesn't Scale

Creating the Initial Plan

The Collaborative Design Process

The Living Document Approach

My Review Process

From Chaos to System

13 tips for better Pull Requests and Code Review

1. Create your PR before the code is ready for review

2. Make people want to review your PR

3. Be your PR’s first reviewer

4. Assign the right reviewers to your PR

5. Be responsive to comments

6. If you want people to review your PRs, you have to review theirs

7. You can review code even if you are a junior developer

8. Check the right things during code review

9. Use the right tone in your comments

10. Be clear about whether a change is required for you to approve the PR or not

11. Review your review before submitting it

12. Approve the PR when the submitter made all the changes you asked

13. Some conflicts can’t be solved in comments

The simplest example to understand Server Actions in Next.js

Build a Guestbook from the 2000s with React Server Components and Server Actions

Fetching the messages from a Server Component

Submitting forms with Server Actions

Improving the form with client features

How to Give Code Review as a Junior Developer?

Why Code Review?

Learn from the Code

Ensure Good Practices

Check for Bugs or Edge Cases

Challenge the Implementation

What Code Review Should Not Be Used For

Code Formatting and Linting

Big Architecture Discussion

What is Expected from a Junior Developer

Read the Code Carefully and Learn from It

Speak Up if Something Isn’t Clear

Share Alternative Perspectives

Use the Right Tone in Your Comments

Use "Why Not" Instead of "You Should"

Be Open and Positive

If You Think Something is Wrong, Suggest an Alternative

How well should I know React before applying to my first job?

You don’t have to know everything

But there are some things you should know

A better learning path for React with server components

Create OG images for your blog with Next.js

@vercel/og, satori, and Edge functions

Generate an image with @vercel/og

An image inside the image

Add OG image to your pages

Combining scripts and DSLs is Kotlin’s most underrated feature

Step 1: Create the domain logic

Step 2: Create a script definition

Step 3: Create builders and the DSL

Custom React hooks to use the browser’s APIs

Access the local storage

Get an element’s size

Get the user’s geolocation

`@vercel/og`, `satori`, and Edge functions

Generate an image with `@vercel/og`