DEV Community: Lorenzo Rivosecchi

How to pin Node.js and PNPM versions in your project

Lorenzo Rivosecchi — Thu, 06 Nov 2025 09:58:13 +0000

When you start working on a new project, it can be hard to figure out how to use the correct versions of Node and PNPM. Today I finally found a strategy that makes sense.

Install node and corepack

I recommend installing node and corepack with brew:

brew install node corepack

The node version will be the latest, because we will let pnpm manage it for us.

Install pnpm with corepack

Corepack allows us to pin a specific package manager and version to our package.json, so open your project folder at the package.json level and run this command:

corepack enable
corepack use pnpm@9

This will add the following line to your package.json

+  "packageManager": "pnpm@9.15.9+sha512.68046141893c66fad01c079231128e9afb89ef87e2691d69e4d40eee228988295fd4682181bae55b58418c3a253bde65a505ec7c5f9403ece5cc3cd37dcf2531"
 }

Now, when someone wants to contribute you can tell them to run

corepack install

You can verify your pnpm version with:

pnpm -v

Pinning Node.js version

Now that you have installed pnpm you can use it to run your scripts with a specific Node.js version.

Add this line to your package.json:

+  "pnpm": {
+    "executionEnv": {
+      "nodeVersion": "20.19.5"
+    },
   }
 }

Now, when you run the next pnpm run command, the specified Node.js version will be downloaded and used instead of the one installed via homebrew.

echo "local: $(pnpm exec node -v)"
echo "global: $(node -v)"

Switching Node.js version globally

PNPM can be used to manage your node.js version outside of your project as well. Here is how you would do it:

pnpm env --global use 20.19.5

If installing node.js with homebrew, to install pnpm through corepack with the intent of using it to install node.js again is too weird, I understand.

As an alternative to this madness, you could install [nvm] or [volta] to manage global node versions, and do the same things to

Enable corepack
Use it to install and pin pnpm version
Use pnpm to pin local node.js version*

*Why is this necessary when i can pin the version with .nvmrc?

The reason is that with .nvmrc you need to remember running nvm use, while the pnpm.executionEnv.nodeVersion will always use the correct node version when calling a script.

How to deploy Google Cloud Functions with PNPM workspaces

Lorenzo Rivosecchi — Wed, 27 Nov 2024 21:53:22 +0000

Are you struggling to deploy your monorepo project because Cloud Build doesn't know what the heck workspace:* means?
You are in the right place! In this blog I'll show you how to trick mister Google into deploying your PNPM monorepo project.

TL;DR

Just bundle everything, and ship the dist folder to Cloud functions with an empty package.json file. Ta-da! 🎩✨

This is how you do it

Create a simple deploy.sh script inside the package that contains the Cloud Function you want to deploy.

#!/bin/bash

# Install dependencies
pnpm install

# Build the project
npx esbuild \
    ./src/index.ts \
    --bundle \
    --platform=node \
    --target=node20 \
    --outfile=./dist/index.js \
    --external:@google-cloud/functions-framework

In this file we simply install the dependencies with PNPM and bundle the source code with esbuild.
The --external:@google-cloud/functions-framework is required because functions-framework should not be bundled for some reason.
If you have some other dependencies that cannot be bundled, for example a module that uses native bindings, you should append another --external flag for that module.

Now, running the deploy.sh script will create a dist folder with the bundled code.
The only thing we are missing now is a package.json, because Cloud Functions pass through Cloud Build, which has trust issues and wants to build everything by itself.
So we are going to trick it with an empty package.json file.
Put this code right after the esbuild command:

jq -n \
  --arg name "@monorepo/functions" \
  --arg version "1.0.0" \
  --arg main "index.js" \
  --arg start "node index.js" \
  --arg build "echo \"No build step\"" \
  --arg ff_version "^3.3.0" \
  '{
    name: $name,
    version: $version,
    main: $main,
    scripts: {
      start: $start,
      build: $build
    },
    dependencies: {
      "@google-cloud/functions-framework": $ff_version
    }
  }' > ./dist/package.json

We use jq to make the code more readable, but you can also use echo to write the JSON directly.
Now we just need to deploy the dist folder to Cloud Functions.
Add this last line to the deploy.sh script:

gcloud functions deploy myFunction \
    --runtime=nodejs20 \
    --trigger-http \
    --source=./dist

And that's it! Now you can deploy your monorepo project to Cloud Functions with PNPM workspaces.

Beyond boring 🙄 markdown rendering with LLMs ✨ and React ⚛️

Lorenzo Rivosecchi — Mon, 28 Oct 2024 09:00:00 +0000

Sometimes rendering LLM outputs simply means taking the response text and shoving it inside a paragraph:

function LLMOutput({ children }) {
   return <p>{children}</p>
}

This works for simple LLM response like "What's your favorite color" but maybe it's not the best solutions for a question like "Explain the reasons that brought us WW1". Complicated topics cannot be well represented by a simple paragraph, in fact if you ask this questions to ChatGPT this is the output:

World War I was ignited by a complex mix of political, economic, and social factors that had been building for years. Key reasons include:

1. **Alliances**: European nations had formed tangled alliances for protection. Germany allied with Austria-Hungary and Italy (Triple Alliance), while France, Russia, and Britain formed the Triple Entente. These alliances created a precarious balance where conflict between two countries could draw in many others.

2. **Nationalism**: Intense pride and competition among European nations fueled tensions. Nationalistic fervor often led to a desire for dominance, particularly in regions like the Balkans, where Slavic nationalism threatened Austria-Hungary's stability.

[...]

If you put this text inside a paragraph it would look pretty bad, that's where Markdown rendering can help you. Let's install a markdown-to-jsx to help us render markdown with React:

npm i markdown-to-jsx
# pnpm add markdown-to-jsx
# yarn add markdown-to-jsx

Then just swap the p tag with the Markdown component:

import Markdown from 'markdown-to-jsx';

function LLMOutout({ text }) {
  return <Markdown>{text}</Markdown>
}

With this simple change, the response is rendered as an expressive document with numbered lists and bold keywords. Beautiful, but we can go further. There is no slideshow syntax in markdown so how do we render this? Half of the answer is in this modified prompt:

Explain the reasons that brought us WW1.
Instead of rendering the reasons as a list, use the Slideshow component like in this example:

'''
# My slides

Below this text, a slideshow will appear 🪄

<Slideshow slides={[{ "id": 1, text: "first slide" },{ "id": 2, text: "second slide" }]}
'''

Here is an answer that ChatGPT gave me with this query:

# Causes of World War I

Below this text, a slideshow will appear :magic:

<Slideshow slides={[
  { "id": 1, "text": "The Rise of Nationalism: National pride and competitive fervor among nations fueled tension. Countries like Germany, France, and Britain were proud of their military power and colonial empires, creating a rivalry that would later ignite conflict." },
  { "id": 2, "text": "The Alliance System: European powers formed alliances for mutual protection. Two major blocs emerged—the Triple Entente (France, Russia, Britain) and the Triple Alliance (Germany, Austria-Hungary, Italy). This network of alliances meant that a conflict between two countries could easily escalate." },
  { "id": 3, "text": "Militarization and Arms Race: With militarization on the rise, nations were investing heavily in their armies and navies. Germany and Britain especially competed in a naval arms race, creating massive fleets, which fostered distrust and prepared them for war." },
  { "id": 4, "text": "Imperialism: European powers were vying for colonial dominance, leading to conflicts in Africa, Asia, and the Balkans. This imperial competition heightened tensions and fueled a sense of entitlement and rivalry among nations." },
  { "id": 5, "text": "The Assassination of Archduke Franz Ferdinand: On June 28, 1914, the assassination of Austria-Hungary’s heir in Sarajevo by a Bosnian Serb nationalist triggered a chain reaction. Austria-Hungary’s ultimatum to Serbia led to a series of declarations of war, dragging the allied powers into conflict." }
]} />

This is great but how do we actually render the slideshow?
The answer is HTML tag overrides! Let's pass some options to the Markdown component to include an override for the non-existent "Slideshow" tag:

import Markdown from "markdown-to-jsx";

const options = {
  overrides: {
    Slideshow: {
      component: Slideshow,
    },
  },
};

function LLMOutput({ children }) {
  return <Markdown options={options}>{children}</Markdown>;
}

function Slideshow({ slides }) {
  return (
    <div>
      <p>This is not a slideshow but you get the point</p>
      <pre style={{ whiteSpace: "pre-wrap" }}>
        {JSON.stringify(slides, null, 2)}
      </pre>
    </div>
  );
}

Et Vue-a-Là, or whatever they say at the end of front-end blogs 🙄

Closing notes

It seems like you can do this also with react-markdown
If you want to play with this you can fork this repo i made
For streaming i recommend accumulating chunks and flushing state updates on newlines

Custom OTP inputs are dumb. Here is how to build one.

Lorenzo Rivosecchi — Sun, 12 May 2024 15:25:44 +0000

As a developer I don't like OTP inputs because they are complicated to build and not clearly defined by a standard.

If I had to choose a single solution to deal with OTPs for the rest of my life I would do this:

<input type="text" autocomplete="one-time-code" />

It's simple, reliable and well integrated with the browser/os.
Someone on Twitter said that whoever implemented the OTP suggestion on Safari deserves a promotion and I agree.

On the other end, One Time Passwords are annoying and confusing to the end users, therefore it might be good to show them a special kind of input to make the experience feel more familiar.

Let's see how we can create a PassCode component in React in less then 200 lines of code.

API Design

I want my component to handle the behavior of an OTP input but allow me to control the styling. Here is how i want to interact with the component:

import { Passcode } from "./passcode";

function OTPInput() {
  return (
    <Passcode>
      <Passcode.Input />
      <Passcode.Input />
      <Passcode.Input />
      <Passcode.Input />
    </Passcode>
  );
}

Why do i want to manually add the input elements?
Because i want to control how many digits are required and also how to style the individual inputs.

Here is how i would apply basic styles with TailwindCSS:

<Passcode className="flex gap-2">
  <Passcode.Input className="w-8 h-8 text-2xl text-center" />
</Passcode>

Let's create the component module now. First we need to establish a way to synchronize the Passcode component with its children.
One solution would be to create a hook that returns utility functions.

const NUMBER_OF_DIGITS = 4;

function OTPInput() {
  const { parentProps, childProps } = usePasscodeState({
    numberOfDigits: NUMBER_OF_DIGITS,
    alphanumeric: true,
  });
  const children = new Array.from({ lenght: NUMBER_OF_DIGITS }).fill(
    (_, index) => <Passcode.Input key={index} {...childProps(index)} />
  );
  return <Passcode {...parentProps}>{children}</Passcode>;
}

This is probably the most idiomatic way to do it, but I would like to avoid wiring everyting up manually.
We can leverage React context + the Children utility to have the same effect, without having to wire up things manually.

Context allows us to pass a props to the Passcode component and read from the child components.
These props will be shared by every input component regardless of their position in the array.

// passcode.tsx
import * as React from "react";

interface ContextValue = {
    alphanumeric?: boolean;
}

const PasscodeContext = React.createContext<ContextValue>({});

export interface PasscodeProps extends ContextValue {
    className?: string;
    children: ReactNode[];
}

export function Passcode(props: PasscodeProps) {
  const { className, children, ...context } = props;

  return (
    <PassCodeContext.Provider value={context}>
      {children}
    </PasscodeContext>
  )
}

export function PasscodeInput() {
    const { alphanumeric } = React.useContext(PasscodeContext)!;
    return <input inputMode={context.alphanumeric ? "text" : "numeric"} />
}

With the Children helper we can pass props that should be different for every input.
For example, let's add a data-index attribute based on the position of the component in the children array.

export function Passcode(props: PasscodeProps) {
  const { className, children, ...context } = props;

  const inputs = React.Children.map((child, index) => {
    const jsx = child as JSX.Element;
    return React.cloneElement<PasscodeInputProps>(jsx, {
        key: index,
        index,
    });
  });

  return (
    <PasscodeContext.Provider value={context}>
      {inputs}
    </PasscodeContext>
  )
}

export interface PasscodeInputProps {
    index?: number;
}

export function PasscodeInput(props: PasscodeInputProps) {
    const context = React.useContext(PasscodeContext)!;

    return (
        <input inputMode={context.alphanumeric ? "text" : "numeric"} data-index={props.index} />
    )
}

As you can see, we are using React.cloneElement to pass additional props to our children.
Essentially, we can avoid doing this:

<Passcode>
  <Passcode index={0} />
  <Passcode index={1} />
  <Passcode index={2} />
  <Passcode index={3} />
</Passcode>

To improve our code we can add a check to see if the passed children is actually a PasscodeInput component.

const inputs = React.Children.map((child, index) => {
  const jsx = child as JSX.Element;
  if (jsx.type !== PasscodeInput) return null;
  return React.cloneElement<PasscodeInputProps>(element, {
    key: index,
    index,
  });
});

Now that we have found a solution to make our API design work, let's implement the behavior of the Passcode component.

Implementation

As mentioned in the intro, the behavior of an OTP input is complicated, let's divide this into chunks.

Storing the code

To track the code input we need to store its value over time.
Let's store the value as an array of strings where each item is a digit of the code:

const [code, setCode] = React.useState<string[]>([]);

Since passcode inputs should have a fixed length, i would modify this a little bit.
Let's extract the number of digits by counting the children:

const numberOfDigits = React.Children.count(children);
const [code, setCode] = React.useState<string>(
  Array.from({ length: numberOfDigits }, () => "")
);

Having defined the number of digits allows us to pre-fill the code with empty string.
This is important because when we assign the digit to the input element we cannot pass it an undefined value, otherwise the component should switch from being uncontrolled to controlled on the first input.

I haven't tested if this is actually needed, but it might be better to prevent the number of children to change between renders. To achieve this we can wrap number of digits in a useState.
The value will always be the one from the first render:

const [numberOfDigits] = React.useState(
  React.Children.count(children);
)

Tracking user input

To track user input we can use the onKeydown event from React. This event will fire for every keystroke, including the Backspace key that will be useful later. Let's define a handler and passit along with the input value.

const handleKeyDown = React.useCallback<KeynoardEventHandler>((event) => {
  /* ... */
});

const inputs = React.Children.map((child, index) => {
  /* ... */
  return React.cloneElement<PasscodeInputProps>(element, {
    /* ... */
    handleKeyDown,
    value: code[index],
  });
});

The PasscodeInput should simply pass both props to the input element:

export interface PasscodeInputProps {
  /* ... */
  onKeydown?: KeyboardEventHandler;
  value?: string;
}

export function PasscodeInput(props: PasscodeInputProps) {
  /* ... */

  return (
    <input
      {/* ... */}
      onKeyDown={props.onKeydown!}
      value={props.value!}
    >
  )
}

Let's dive into the handleKeydown function implementation.
The main responsibility is to read the key pressed and modify the state when necessary.

const handleKeyDown = React.useCallback<KeynoardEventHandler>((event) => {
  const target = event.target as HTMLInputElement;
  const index = Number(target.dataset.index);
  const keyPressed = event.key;

  setCode((prev) => {
    const next = [...prev];
    next[index] = keyPressed;
    return next;
  });
});

Let's handle the backspace key now:

/* ... */
const isBackspace = keypressed === "Backspace";

if (isBackspace) {
  setCode((prev) => {
    const next = [...prev];
    next[index] = "";
    if (index > 0) next[index - 1] = "";
    return next;
  });
} else {
  /* ... */
}

Finally, let's protect us from unwanted keys:

// default US-104-QWERTY keyboard
const invalidKeys = [
  " ",
  "!",
  "#",
  "$",
  "%",
  "&",
  "(",
  ")",
  "*",
  "@",
  "Alt",
  "AltGraph",
  "ArrowDown",
  "ArrowUp",
  "Backspace",
  "CapsLock",
  "Control",
  "Delete",
  "End",
  "Enter",
  "Escape",
  "Fn",
  "Home",
  "Meta",
  "OS",
  "PageDown",
  "PageUp",
  "Shift",
  "Symbol",
  "Tab",
  "^",
];

/* ... */

const handleKeyDown = React.useCallback<KeynoardEventHandler>((event) => {
  if (invalidKeys.includes(event.key)) return;
  /* ... */
});

Managing input focus

OTP inputs are expected to move focus automatically to the next area after a digit is inserted.
We can achieve this by defining a utility function called moveFocus and use it inside our onKeydown handler.

First, let's attach a ref to the wrapping div of the Passcode component:

export function PassCode(props: PassCodeProps) {
  const containerRef = useRef<HTMLDivElement>(null);
  /* ... */

  return (
    <div ref={containerRef}>
      <PasscodeContext.Provider value={context}>
        {inputs}
      </PasscodeContext>
    </div>
  )
}

Now, let's define the utility as a function that receives an index number, retrieves the dom node and calls focus on it:

const moveFocus = useCallback((index: number) => {
  const next = containerRef.current?.children[index];
  if (next instanceof HTMLInputElement) next.focus();
});

And now, let's move focus to the next input when a key is inserted, and to the prev element when the key is backspace:

if (isBackspace) {
  moveFocus(index - 1);
  // ...
} else {
  moveFocus(index + 1);
  // ...
}

Enabling Copy and Paste

To allow copy and paste we can use the onPaste event from React.
Same as before, we create the callback on the parent and pass it to the children, which in turn should pass it to the input element.

The handlePaste function should grab the text with event.clipboardData and call setCode accordingly:

const handlePaste = useCallback<ClipboardEventHandler>(
  (event) => {
    event.preventDefault();
    const target = event.target as HTMLInputElement;
    const index = Number(target.dataset.index);

    const pasted = event.clipboardData.getData("text");
    const length = pasted.length;

    if (length >= numberOfDigits) {
      moveFocus(numberOfDigits - 1);
      setCode(Array.from(pasted.slice(0, numberOfDigits)));
    } else {
      moveFocus(index + length);
      const next = [...code];
      for (let i = index; i < numberOfDigits; i++) {
        next[i] = pasted[i - index] ?? "";
      }
      setCode(next);
    }
  },
  [setCode, moveFocus, numberOfDigits, code]
);

One thing to not is that in order to make CTRL or CMD+V work we need to make sure that when the combination of keys is pressed, the handleKeydown isn't preventing the default behavior of the browser:

const handleKeyDown = React.useCallback<KeynoardEventHandler>((event) => {
  if (event.metaKey && event.key.toLowerCase() === "v") return;
  event.preventDefault();
});

Not sure what good does it make to call event.preventDefault anyways, but if you call it, make sure it doesn't happen while pasting.

Adding accessibility labels

One reason why custom OTP inputs are dumb is that since the input is split into multiple elements, the screenreader experience tends to be pydantic.
Maybe there is a better solution, here is how I would approach this.

const labels = [
  "First input digit",
  "Second input digit",
  // ...
];

export function PassCodeInput(props: PassCodeInputProps) {
  // ...
  const id = `passcode-input-${props.index}`;
  const label = labels[props.index];

  return (
    <>
      <label htmlFor={id}>{label}</label>
      <input id={id} {/* ... */} />
    </>
  );
}

If you wanna go through the accessibility rabbit hole there are more things to consider.
I would probably make sure to add some context on the page to let the user know what these input digits are about.

<h1>Enter verification code</h1>
<Passcode>
  {/* ... */}
</Passcode>

Validating the input

How you validate the input can vary, but overall you could add an onComplete callback to the Passcode component and call it when the onKeyDown or onPaste handlers have set the last digit.

export interface PasscodeProps {
  // ...
  onComplete?: (code: string) => void;
}

export function PassCode(props: PassCodeProps) {
  // ...

  const handleKeyDown = () => {
    ///...
    if (index === numberOfDigits - 1) {
      props.onComplete?.(code.join(""));
    }
  };

  const handlePaste = () => {
    // ...
    if (next.every((digit) => digit !== "")) {
      props.onComplete?.(code.join(""));
    }
  };
}

If validation is async (likely) you can add an isValidating prop to the Passcode component and disable the inputs when is set to true. Allowing you to do something like this on:

import { Passcode } from "./passcode";
import * as React from "react";

async function validate(code: string) {
  const response = await fetch("https://backend.app.com/auth?code=" + code);
  return response.ok;
}

function OTPInput() {
  const [isValidating, setIsValidating] = useState(false);
  const handleComplete = React.useCallback((code: string) => {
    validate(code).then().catch(console.error);
  }, []);

  return (
    <Passcode onComplete={handleComplete} isValidating={isValidating}>
      <Passcode.Input />
      <Passcode.Input />
      <Passcode.Input />
      <Passcode.Input />
    </Passcode>
  );
}

Conslusions

In this article i have left out aspects of the behavior that are subjective.
For a full review of the code refer to the github repository.

OAuth2 and AWS Cognito for Browser Extensions

Lorenzo Rivosecchi — Mon, 15 Apr 2024 10:25:08 +0000

This is a guick guide on how to do OAuth2 logins within a chrome extension. Let's get started:

Step 1: Register the Extension

OAuth2 requires a static URL to redirect the client after the authentication with the third party server is completed.
Since Browser Extensions are bound to a traditional URL, browsers rely on a trick.

Extensions can be registered to the Chrome Webstore and obtain a subdomain on chromiumapps.org:

<extension-id>.chromiumapps.org

After an OAuth2 flow is initiated, the browser will listen for redirects on that URL and expose the authentication code through a special API, more on this later.

To register the extension follow this guide from Google.

Before proceeding, make sure that your manifest.json contains the following fields:

{
  "key": "-----BEGIN PUBLIC KEY-----...",
  "permissions": ["identity"]
}

Step 2: Setup AWS Cognito

Assuming that you already have a Cognito User Pool,
the next step is to create a client application.

Set the redirect URL to the following:

https://<extension-id>.chromiumapps.org/

Take note of the Client ID issued by AWS Cognito and put it in the manifest.json of your extension.

{
  "oauth2": {
    "client_id": "<your-client-id>",
    "scopes": ["email", "openid", "profile"]
  }
}

Step 3: Write the Code

Here is how the auth flow will look like:

User installs the App
Browser opens a new tab with an auth page
User clicks on Login
Browser opens a popup window with cognito hosted ui
User logs in from the popup
Browser closes popup and show success message

Open new tab on install

Add the following code to your background script:

// background.js
browser.runtime.onInstalled.addListener(async () => {
  browser.tabs.create({
    url: browser.runtime.getURL("auth.html"),
  });
});

Create login button

Add an auth.html page to your extension folder with a login button and a script tag pointing to auth.js

<head>
  <title>Auth</title>
</head>
<body>
  <button id="login_button">Login</button>
  <script src="/auth.js"></script>
</body>

Connect the button to a login function that we are going to complete later.

async function login() {
  console.log("Logging in...");
}

const loginButton = document.getElementById("login_button");

loginButton.addEventListener("click", () => {
  login().catch(console.error);
});

Initiate OAuth2 flow

Let's complete the login function step by step.
First, let's define some variables to use as parameters for
the auth server:

const manifest = browser.runtime.getManifest();

const AUTH_DOMAIN = "<your-cognito-server-domain";
const AUTH_CLIENT_ID = manifest.oauth2.client_id;
const AUTH_REDIRECT_URL = browser.getRedirectUrl("/");
const AUTH_RESPONSE_TYPE = "code"; // recommended
const AUTH_SCOPE = browser.oauth2.scopes.join(" ");

Then we use them to build an authorization request:

// https://docs.aws.amazon.com/cognito/latest/developerguide/authorization-endpoint.html
const authorizeUrl = new URL("oauth2/authorize", `https://${AUTH_DOMAIN}`);

authorizeUrl.searchParams.set("client_id", AUTH_CLIENT_ID);
authorizeUrl.searchParams.set("redirect_uri", AUTH_REDIRECT_URL);
authorizeUrl.searchParams.set("response_type", AUTH_RESPONSE_TYPE);
authorizeUrl.searchParams.set("scope", AUTH_SCOPE);

Now it's time to call a api that will open the popup for us and tell the browser to listen for a redirect to <extension-id>.chromiumapps.org.

const redirectUrl = await browser.identity.launchWebAuthFlow({
  url: authorizeUrl.toString(),
  interactive: true,
});

If your have set response_type to code, the redirectUrl
variable should look like this:

https://<your-extension-id>.chromiumapp.org/?code=1234

We can easily get the code using the URL class:

const authCodeUrl = new URL(redirectUrl);
const authCode = authCodeUrl.searchParams.get("code");

Obtain a session token

Let's now exchange the code with a token using another endpoint from AWS Cognito:

const tokenUrl = new URL("oauth2/token", `https://${AUTH_DOMAIN}`);

const tokenRes = await fetch(tokenUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    code: authCode,
    grant_type: "authorization_code",
    redirect_uri: AUTH_REDIRECT_URL,
    client_id: AUTH_CLIENT_ID,
  }),
});

if (!tokenRes.ok) {
  throw new Error("Failed to fetch token");
}

const token = await tokenRes.json();

This token can now be stored for future use.
Since we are inside a Browser Extension, the recommended approach is to use the browser.storage api instead of localStorage.

await browser.storage.local.set("token", token);

Make sure to add the storage permission to your manifest.json

Get user info

Now that we have a session token we can call the userInfo endpoint to retrieve the users email, username and other data depending on the setup.

// auth.js

async function fetchUser() {
  // Retrieve token from storage
  const storageGetResult = await browser.storage.get("token");
  const token = storageGetResult["token"] as Token | undefined;
  if (!token) throw new Error("Not logged in.");

  // Fetch user info using the access token
  const userInfoUrl = new URL("oauth2/userInfo", `https://${AUTH_DOMAIN}`);
  const userInfoRes = await fetch(userInfoUrl, {
    headers: {
      Authorization: `Bearer ${token.access_token}`,
    },
  });

  const user = await userInfoRes.json();
  return user;
}

Logout

Finally, let's write a function to log out the user by revoking the token and removing it from the local store:

// auth.js

async function logout() {
  // Retrieve token from storage
  const storageGetResult = await browser.storage.get("token");
  const token = storageGetResult["token"];
  if (!token) throw new Error("Not logged in.");

  // Revoke token on the server using the refresh token
  const url = new URL("oauth2/revoke", `https://${AUTH_DOMAIN}`);
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: new URLSearchParams({
      token: token.refresh_token,
      client_id: AUTH_CLIENT_ID,
    }),
  });

  if (!response.ok) throw new Error("Failed to revoke token");

  // Remove the token from storage
  await browser.storage.local.remove("token");
}

Conslusions

And that's it. You should have all you need to develop a Browser Extension with OAuth2 and AWS Cognito.

Using OpenAI to control an Ableton Live Session 🎼

Lorenzo Rivosecchi — Fri, 16 Feb 2024 11:17:40 +0000

In this blog post i'll show you how to create an agent that receives instructions in natural language and performs actions on your Ableton Live instance. To keep it simple i'll just show you how to get and set the song tempo, but the same concepts can be applied to obtain more complex behaviours.

TLDR;

Here is the code repository:
https://github.com/fibonacid/ableton-live-assistant

Requirements

Ableton Setup

To build our agent we first need to establish a communication between our Node.js app and Ableton Live.
We can use a program called AbletonOSC to register a control surface that listen for commands over the network.

To install AbletonOSC refer to the Installation section.

Node Setup

Create a directory called ableton-live-assistant, then open a terminal inside it and run this command:

npm init -y

Now, let's install some dependencies:

npm i dotenv openai osc-js

dotenv: To load the OpenAI API key from a .env file.
openai: To call the GPT-4 API.
osc-js: To send commands to Ableton Live.

OpenAI Setup

If you are new to OpenAI, refer to the Quick Start guide to create an account and get an API key.

Once you have your API key, create a file called .env in the root of your project and add the following line:

OPENAI_API_KEY=your-api-key

⚠️ If your are using git, make sure to add .env to your .gitignore file.
This will prevent your API key from being exposed in case you push your code to a public repository.

echo .env >> .gitignore

Loading the API key

Create a file called index.mjs and add the following code:

import { config } from "dotenv";

// Load the environment variables
config();

// Print the API key to make sure that it was loaded correctly
console.log(process.env.OPENAI_API_KEY);

We use the mjs extension to enable ES6 module syntax.

Let's try to run our code:

node index.mjs

If everything is working, you should see your API key printed in the terminal.

Testing the OpenAI API

Before going too deep, let's demonstrate basic usage of the OpenAI API.
We are going to call the api with the question "Hello, how are you" and print the response.

import { config } from "dotenv";
import OpenAI from "openai";

// Load environment variables
config();

// Create an instance of the OpenAI client
const openai = new OpenAI(process.env.OPENAI_API_KEY);

async function main() {
  // Send a message to the chat model
  const completion = await openai.chat.completions.create({
    model: "gpt-4",
    messages: [{ role: "user", content: "Hello, how are you?" }],
  });
  // Unpack the response and print it
  const response = completion.choices[0]?.message?.content;
  console.log(response);
}

main();

Run the code and you should see the response printed in the terminal.

As an artificial intelligence, I don't have feelings, but I'm here, ready to assist you. How can I help you today?

Creating an Agent

An agent is roughly a program that listens for commands and performs actions based on them. To achieve this with GPT-4 we can use OpenAI's Function Calling API.

The idea is to provide some tools to our model that can be used to perform actions. The model will try to interprate the verbal commands and decide which tool to use.

Let's demonstrate by modifying our previous code to ask the model what time it is.
The model cannot know the answer to this question because it doesn't have access to the system clock, but we can provide a tool that returns the current time.

import { config } from "dotenv";
import OpenAI from "openai";

// Load environment variables
config();

// Create an instance of the OpenAI client
const openai = new OpenAI(process.env.OPENAI_API_KEY);

async function main() {
  const messages = [{ role: "user", content: "Hello, what's the time?" }];

  // Send a message to the chat model
  const completion = await openai.chat.completions.create({
    model: "gpt-4",
    messages,
    tools: [
      {
        type: "function",
        function: {
          name: "get_current_time",
          description: "Returns the current time",
        },
      },
    ],
  });
  // Unpack the response and grabs the first tool call
  const response = completion.choices[0]?.message;
  const toolCall = response?.tool_calls[0];

  // Store reply in the messages array
  messages.push(response);

  // Check if the tool call is the get_current_time function
  // This is a simple example, but you could have multiple tools
  if (toolCall.function.name === "get_current_time") {
    // Get current time from the operating system
    const currentTime = new Date().toLocaleTimeString();

    // Store function call result in the messages array
    messages.push({
      role: "tool",
      tool_call_id: toolCall.id,
      name: toolCall.function.name,
      content: currentTime,
    });
  }

  // Send new completion with the updated messages array
  const secondResponse = await openai.chat.completions.create({
    model: "gpt-4",
    messages,
  });

  // Print out the natural language response
  console.log(secondResponse.choices[0].message.content);
}

main();

Run the code and you should see the response printed in the terminal.

The current time is 11:20:02 AM.

Controlling Ableton Live

Now it's time to put everything together and create an agent that can control Ableton Live.

We are going to create a tool that can set and get the song tempo.
First, let's create some helpers to send and receive OSC messages.

// other imports...
import OSC from "osc-js";

const osc = new OSC({ plugin: new OSC.DatagramPlugin() });

// Listen for OSC messages on the specified port and host
osc.open({
  port: 11001, // the port used by AbletonOSC
  host: "0.0.0.0", // accept messages from any host
});

// Send an OSC message to the specified address
function sendMessage(address, ...args) {
  return osc.send(new OSC.Message(address, ...args), {
    port: 11000, // the port used by AbletonOSC
    host: "127.0.0.1", // the host where AbletonOSC is running
  });
}

// Wait for an OSC message on the specified address
function waitForMessage(address) {
  return new Promise((resolve) => {
    osc.on(address, (message) => {
      resolve(message);
    });
  });
}

// rest of the program...

Now let's define the functions to get and set the song tempo.

async function getTempo() {
  const address = "/live/song/get/tempo";
  await sendMessage(address);
  const message = await waitForMessage(address);
  return message;
}

async function setTempo(bmp) {
  const address = "/live/song/set/tempo";
  await sendMessage(address, bmp);
  const message = await waitForMessage(address);
  return message;
}

Redefining the Agent

Now that we have a method to control Ableton we can extend our agent to use it.
First, let's add a system prompt to make the agent aware of its responsibilities.

const messages = [
  {
    role: "system",
    content:
      "You are a smart Ableton Live controller. You receive commands in natural language and use tools to interact with the Live set.",
  },
  { role: "user", content: "Hello, what's the song tempo?" },
];

Then, let's redefine the tools to include the get and set tempo functions.

const tools = [
  {
    type: "function",
    function: {
      name: "get_song_tempo",
      description: "Get the tempo of the current song",
    },
  },
  {
    type: "function",
    function: {
      name: "set_song_tempo",
      description: "Set the tempo of the current song",
      parameters: {
        type: "object",
        properties: {
          bpm: {
            type: "number",
            description: "The new tempo in beats per minute",
          },
        },
        required: ["bpm"],
      },
    },
  },
];

Then, let's modify the code to handle different types of tools calls:


// Unpack the response and grabs the first tool call
  const responseMessage = completion.choices[0]?.message;
  const toolCalls = responseMessage?.tool_calls;

  // Check if the response contains a tool call
  if (toolCalls) {
    // List available functions
    const availableFunctions = {
      get_song_tempo: getTempo,
      set_song_tempo: setTempo,
    };
    // Extend conversation with the tool call
    messages.push(responseMessage);

    // Iterate over the tool calls and execute the corresponding function
    for (const toolCall of toolCalls) {
      const functionName = toolCall.function.name;
      const functionToCall = availableFunctions[functionName];
      const functionArgs = JSON.parse(toolCall.function.arguments);
      const functionResponse = await functionToCall(functionArgs);

      messages.push({
        tool_call_id: toolCall.id,
        role: "tool",
        name: functionName,
        content: functionResponse.toString(),
      }); // extend conversation with function response
    }

    // same as before...

Now, let's run the code and see if it works.

The current song tempo is 120 beats per minute.

Conclusion

The possibility of fusing the expressivity of natural language with the precision of software is fascinating.
This post was a bit rushed, but i hope it gave you an idea of how easy it is to create a conversational agent that controls Ableton Live.
In the future I might get back to this topic and show you how we could expand on this to make the agent a good companion for music production.

How to setup a Node for Max project with TypeScript

Lorenzo Rivosecchi — Thu, 01 Feb 2024 11:47:33 +0000

In this blog post I'll show you how to setup a Node 4 Max project with TypeScript. The project will live in a Git repository for versioning and will feature build and watch scripts for hot reloading.

TLDR;

If the explanation is too long for you, you can just clone the repository and start from there.
Here is a oneliner to download the code without the Git history:

npx degit github:fibonacid/n4m-typescript

Requirements

Install Max MSP

Make sure you have the latest version of Max MSP installed.
At the time of writing, the latest version is 8.6.0, which contains a local instance of NodeJS 20.6 (Release Notes)

To download Max MSP go to https://cycling74.com/downloads

Install NodeJS

Even though Max MSP bundles NodeJS internally, you still need to run node on your terminal to setup the project. I recommend installing NVM to manage your node versions.
Once you have NVM installed, run the following command to install the version we need.

nvm install 20.6

Create Max Project

To simplify the management of multiple patchers and assets, Max MSP introduces projects. A project can be created by opening the Max MSP app and go to File > New Project.

Now you should see a floating panel for your project.
Click on the plus icon on the bottom and create a new pather file called main.maxpat;

Once you have created the patcher, your project folder should look similar to this:

.
├── n4m-typescript.maxproj
└── patchers
    └── main.maxpat

Setup Node environment

Since this is going to be a Node project, we need to create a package.json file, where our scripts and dependencies will be configured.

Check node version

First, check if your are running the correct Node version:

node -v

The command should print out v20.6.1.
If see a different version and you have installed NVM, you can switch to the right version with:

nvm use 20.6

Create package.json

To create the file, you can run this command inside the project directory.

npm init -y

Now you should have a package.json file that looks like this:

{
  "name": "n4m-typescript",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Set engine version

We want to make sure that the project is running the correct Node version. To do so, we can add an engines property to the package.json file.

+  "engines": {
+     "node": ">=20.6"
+  },

This config makes node and npm throw an error if the node version is not compatible with the one specified.

Setup TypeScript

To make TypeScript work with Node and Max we need to install some dev dependencies:

typescript is the compiler for TypeScript
@tsconfig/recommended contains the recommended TypeScript configuration
@types/node contains the type definitions for Node
@types/max-api contains the type definitions for Max API bindings

Run this command to install the dependencies:

npm i --save-dev typescript @types/node @tsconfig/recommended @types/max-api

After the installation, you should see a new node_modules folder and a package-lock.json file.

node_modules: folder that contains all the dependencies
package-lock.json: file that contains the exact version of the dependencies installed

Additionally, the dependencies will be added to the package.json file like this:

+  "devDependencies": {
+    "@tsconfig/recommended": "^1.0.3",
+    "@types/max-api": "^2.0.3",
+    "@types/node": "^20.11.15",
+    "typescript": "^5.3.3"
+  }

Now, let's create a simple tsconfig.json for our project.

{
  "extends": "@tsconfig/recommended/tsconfig.json",
  "compilerOptions": {
    "noEmit": true,
    "module": "ES2015",
    "moduleResolution": "Bundler"
  },
  "include": ["src/**/*"]
}

Since we have specified noEmit, TypeScript will perform type checking without generating any JavaScript files.
To transform TypeScript into JavaScript we need to use a bundler. In this case we are going to use ESBuild because is fast and easy to configure.

Bundling is necessary because Max MSP doesn't support ES Modules very well. ESBuild will concatenate all the JavaScript modules that we need into a single file that we can load in Max.

Setup Bundler

To install ESBuild, run this command:

npm i --save-dev esbuild

Now let's create our application entry point inside src/main.ts:

import { MaxAPI } from "max-api";

// It will post a message in the Max console
// when the script is run by the `node.script` object
maxAPI.post("Hello from TypeScript!");

To bundle the application, we need to create a build script in the package.json file:

   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "esbuild src/main.ts --bundle --platform=node --external:max-api --target=node20 --outfile=dist/main.js"
   },

You might have noticed a few flags in the command:

--bundle: tells ESBuild to bundle all the dependencies into a single file
--platform=node: tells ESBuild that the target platform is Node
--external:max-api: tells ESBuild to not bundle the max-api dependency
--target=node20: tells ESBuild to target Node 20
--outfile=dist/main.js: tells ESBuild to output the bundled file in the dist folder

Now, if you run npm run build you should see a dist folder with a main.js file inside.
To make it available inside our patcher, we need to open the Max Project window and click on the + icon on the bottom. Select Add Existing Files and select the dist/main.js.

Connecting Max to the application

The last piece of the puzzle is to connect the patcher to the application.
To do so, I recommend copy and modify the helper patch for node.script and modify it to fit our needs.

The node object should look like this, everything else is optional:

node.scripts main.js @autostart 1 @watch 1

node.script: name of the max object
main.js: filename of the bundled application
@autostart 1: tells the object to start the application when the patcher is loaded
@watch 1: tells the object to reload the application when the main.js is modified

Here is a compressed version of the patch that you can copy and paste inside main.maxpat:

<pre><code>
----------begin_max5_patcher----------
2632.3ocuasziiiaD9r6eEDBYvdoaOjTumbYFjbIAYytHytHG1YggrEsM6QV
TPjtc2Yw9eO7gjrjrjaYaIO.s8HRIyu5iUUrXUT+wCyrVxdkvs.eB7afYy9i
GlMS2jpgYEWOyZWzqqRh35ayZEa2NRpv5QSeBxqBc6+Jm.9bzdAiKhxE.D3v
VRJ3M19b.eUNMS.3aY6ShAl9YoqHpdArL4sI1R.YQhUaK+YSnojUr8o5eabQ
izX8HwV97SHT4clteGMMgHznCcrQ1dQYqvhV0i.McyhbxJgQlsClCeD33DN2
8Q.F5q9x1dND76pG4Oe3A0GONPpIkbPhsSXlbITHf78ooxwtrWC7DukQL.wx
5Q4efeuCQsSIE2ojh6WRwtPsn54n9xOT8IFekRZeJA.v+hl9c9mJ6X4lUrDV
tAAv41vv.ncHF45E3g8eT0Dx2ywG5FDfscwgO10cgTn7ThwAWNLqYoBN8+oo
RjR9NBqZiORIxM9n5W81Th7jZLR8FjlfQgNZcoqkZEQK6UGgpn71pJxGnv.1
5mT1R+yuB9xO+O.+c1Jt5F0s8uYwDvZVN3GidE7SuPxegRNn5U0wb4S7eIK4
TAQ2zO+iUW1o9nuUEUjGsiHH4KHoQKSH0ook6EBVZK5783X6ihTC8FmPHJzC
5G3Xir8seT2TccDWUStsUkpOC24zFVMgY6Xl17zeAQiqwel1AWrdxvz0VZbL
oAyTib8sFIMRsnIIKswN5nwd8mgjWHOEBjzPhlPjZGbZiotYVQYY0ZdVsGQw
BOaloBdrpIZpoIuplxIuPKedXUqQ4RjKjvdetV6w5UOGqi+LRky7z8TMTLMJ
mOJfjl4Sk5e7rnUlGVMAU18Qt.AMbAzV8kmiwMX.7Han7SkvV8cRbczYol3n
oY4DtzUWjnE3shIqi1mHVzv4Cddm8ut.hc1oRHz3+K4znjJIXSNMlkp.QioB
UykCmT3b0xlacgQeGoQYc7vRULIuzSmxElE64KixUyTEly3xNELVRytpdtDx
ZQQ2YzzzVrnfk0em4zMaOyytjI6b249s08vWrO0z6BoRgXAO5klrsHJIov9r
4O+qQozcQBhfZlBvvpNMtz1JicgkjzPdM87RG8DKUxWQNPiEa0CTckASPPEJ
QVUyxwzMDtnYahnM7lsvEuYH8ZMseYgQ7BAYWVRjn0MHMOnbgLnqC7harTQq
NAbL3u5F00c10n8VN8jVe7nMjJS15d9jSrY7O8wOlJshelOmku4ijzOV+VOM
FnJk3VtEcq+XcEGTGtGQ05oqH+PZuhgX8R2XTy3glUt.PgSmIjeNb3v7zrcR
JRFU0UxONiO+33YWiercmD9owhlsV3bkz0nzB65HD+dIDz0RHgtFlPu9g68W
eIgEEC9lUmgxMW9qHg72rtN1xd7UeLrkQ6AqiI+tp8X1yETtMTLv97jxis9q
ORB2KI41KI4ddRRGclqItDr+jvQZTdVBPsoh9jYTuxL7ZULLQjpC7FV9Yigu
buk0WLSCqzXxq0BEbxUgHaHulA9l7ebvmkK2xETgRq5Ce.CGGUp.zU3lZH5T
XOyVb87t2FdRu1RmS6j.aKHUFz7KDvRFS7t704zBsctBZBODZB5X7oGduoId
VtThWC3uovLPsuKYn.ef+QsV97shcW4BeXuwekOCWYizbUf+cekuTmcOEkQe
p1tnuTVYBBfz+X3QAn6s9SzRNKQ5LRYmccTBxYhTTP9ZNwO7tqm7W+Vt7dAI
Q6SWscYtbiOjbveogO1txq7kRbvIRWxF4a1Khl4rc6g4NtQekvzy12zigp+t
oTNae9pRIsXgdPykgk6XUPSqR6wuUEDDXnSnWLFbFHHrO8F2QiyXROpEzAxS
yjE4z63ESDxwCk8bmP5SABzPXuIFC1C.CNSLFvC.CS5bg6.0HPCUUtHQeGuX
pPt2.Qd.ZXHG6VyHTewDgb6ABb+Ibd2dntv5fl6l8LKFT6hIB4CE3pU+NOvc
Lq+aax2tA45KlHj6NZH2FCuqHO.MZPuPAIntsVfWuQP7P8ZoXoxWd7BSsAVD
ID4zkxPK4sKNzEkC6MIrkQIsR7bWo39gifajJB8+g7BIJQelBL.15z5r4VUg
58KaVOiarxaNgAFS0BO0lcK4bkEUrYzt0yMgRD6+rDzUcasufyQ.5LBXwYkv
HfNna5bDTVBiRnoxkotDSzDp3s5HgsdMmHJKHLTUu2iUyzT7t3boRUUQYJmi
VkPW8cw1b19Maq29I02oYGubZGlQor1aUE5dipLkMZgkGaJsJruInkQoa5bR
xqZRpzjQt4246XoTAKuHKuWPIhOy7ncnYdLPu.iCDZlHgi7IB4WjVgG1xRHf
0Q6nIuAXqKOOPEI3GTnjyG5Y+wYjJRtiNgFXOSNfLGOlq9r+zmkZgr9tm9mN
OfKnQxjUKn1d5uBruIK12QNSy1Ad5oxyJvk4eJbTkVn4L4ztzCiq3lkyVIui
upqb9EJttip3ZapSGJbJEW90Hm1ipbFp+x2cZESV1kIj3fwQHCMQdFpSDjm6
jbF89JgniM5YtNsy5ZIRSWy.rTvV1AffAhhiK8JC1FkFmHsmGp24pDPWDZkN
JUyog.cYwbYtMNMlzOWdti1omNZdji43+3oOomtWKaJG1kGiSoyRXz6h5UYe
9rmXtArXF9bRqYYLipiKbRrOHq1xNlP0gZaLRN.Jjvh.OcsmDii+1VxpuqMO
TkWWFgBmUXhDAxI7LYCDkEh5NTy2fVT06Zcf505.eWsNJxReo0Q.7lrNJNsm
Wb3tnvQxx3L5MpD+dzxv19lByquS4opZd.4cpNrSOsLhSWA9bFKaeF.0wtOQ
tiSDr3hyhRfotK9ShIwWRRNITcPTNQF7CYM8URL3.UrE7ClEO+gAeB9crtqJ
7FtpTe291VM38iSJWbYdIQ3wwKYgXVDAg2MoQzixtRGedgjtKhlNWFIQi27i
OePgK.5JdWGfVW9pgsOh+v49NHjum5+YN13u6QA2vZNXyhJFkiFmW5AlhrJV
n0wBcci7ALSSgKVRSWnqeaiLiI2AUO8nY0iG.lqJmYOy2SGfh4oovniCBkEc
SJSxgpDrzTq7Bck+LOJeydkymxWjgZpXppZAa7lZzggfJP1pLlrkjjESDQzD
tT0z5LqLXrULNQMao.gt1UFFCl049yrWJwJ+8dGVE6aLlJpXkbC3XnqKxFBg
NAA3.jZWbsHYMJZVOaCm2Nk5EL+o0NFVu5m8kF8iU94jI2KZffu2.4NFiDdH
iDbLFovKXjJtoV0e.CMK0X6OW8x3fM4VTe0MBNr8MCNaeSRfbCqCN8U2J3Bt
Yvod8TJ3pFD2sBsam1bbMISxyrYRCx75OAwCFY2NzLG+5BWLFj4brn3WOxbG
IjY6VCY5KtUjENVHCGTCYpKtQj4fFKjETmyBtcNCc27TOf0d7NqCJjQE1bdk
rCMKf13JrwGlCLr5paE09CfeZdO0d0EuM2lCwNCaexTiILgVuLhpAo0KgXqW
.wSe4C6+EOr8KcntH488xF9ve9v+GaJmA+.
-----------end_max5_patcher-----------
</code></pre>

ChatGPT clone with React Suspense and Streaming

Lorenzo Rivosecchi — Mon, 29 Jan 2024 13:45:55 +0000

This is a short blog to showcase a solution I developed to create ChatGPT style interfaces.

Server Side

Let's start by creating a simple server that our client will use to communicate with OpenAI.
First, we initialize the openai client with our API key:

import OpenAI from "openai";

const openai = new OpenAI(process.env.OPENAI_API_KEY);

Then we create a map to store chat sessions:

const sessions = new Map<string, OpenAI.ChatCompletionMessageParam[]>();

Now we define a request handler that will forward messages to OpenAI and stream the response down the wire:

import express from "express";
import bodyParser from "body-parser";

const app = express();

// Parse body as JSON when Content-Type: application/json
app.use(bodyParser.json());

app.post("/chat", async (req, res) => {
  // 1. Validate input
  // 2. Create session if it doesn't exist
  // 3. Add user message to session
  // 4. Fetch response from OpenAI
  // 5. Stream response to client
  // 6. Add OpenAI response to session
});

app.listen(3000, () => {
  console.log("Listening on port 3000");
});

Let's start by validating the input.
We expect to receive a session ID and a prompt from the client.

// 1. Validate input
const prompt = req.body.prompt;
const sessionId = req.body.sessionId;

// Validate input
if (typeof prompt !== "string" || prompt.length === 0) {
  res.status(400).send("prompt is required");
  return;
}
if (typeof sessionId !== "string" || sessionId.length === 0) {
  res.status(400).send("sessionId is required");
  return;
}

Then, if session doesn't exist, we create it and add the user message to it.

// 2. Create session if it doesn't exist
if (sessions.has(sessionId) === false) {
  sessions.set(sessionId, []);
}
const messages = sessions.get(sessionId);

// 3. Add user message to session
messages.push({
  role: "user",
  content: prompt,
});

Now we can fetch the response from OpenAI using the stream option.

// 4. Fetch response from OpenAI
const stream = await openai.chat.completions.create({
  messages,
  stream: true,
  model: "gpt-4",
});

The stream object is an async iterable, so we can use a for await loop to iterate over the incoming chunks. To stream the chunks to the client we simply write to the response object with res.write. Once the stream is finished, we call res.end to close the connection.

// 5. Stream response to client
let response = "";
for await (const chunk of stream) {
  const token = chunk.choices?.[0]?.delta?.content ?? "";
  res.write(token);
  response += token;
}
res.end();

Finally, we add the OpenAI response to the session.

// 6. Add OpenAI response to session
messages.push({
  role: "assistant",
  content: response,
});

Client Side

Let's now focus on the client side. We will use some React APIs that are currently available in the canary release of React 18. Let's start by preparing our environment.

Update you react version to the latest canary release:

npm update react@canary react-dom@canary
# yarn upgrade react@canary react-dom@canary
# pnpm update react@canary react-dom@canary

Then, reference the canary react types in your tsconfig.json:

{
  "compilerOptions": {
    "types": ["react/canary"]
  }
}

If you prefer to use a declaration file you can use a triple-slash directive instead:

/// <reference types="react/canary" />

Now we can start building our app. Let's start by creating a simple form to send messages to the server.
The component will accept a callback to send messages to the server and a boolean to indicate if the server is currently processing a message.

import { useState, useCallback } from "react";
import type { FormEventHandler, ChangeEventHandler } from "react";

export type ChatFormProps = {
  onSendMessage: (message: string) => void; 
  isSending: boolean;
};

export function ChatForm({ onSending, isSending }: ChatFormProps) {
  const [input, setInput] = useState("");

  const handleSubmit = useCallback<FormEventHandler<HTMLFormElement>>(
    (e) => {
      e.preventDefault();
      if (input === "") return;
      onSendMessage(input);
      setInput("");
    },
    [input, onSendMessage],
  );

  const handleInputChange = useCallback<ChangeEventHandler<HTMLInputElement>>(
    (e) => {
      setInput(e.target.value);
    },
    [],
  );

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={input}
        onChange={handleInputChange}
        placeholder="Ask a question"
        required
      />
      <button disabled={isSending}>{isSending ? "Sending..." : "Send"}</button>
    </form>
  );
}

Now, we create a parent component that will handle the communication with the server.

import { useState, useCallback } from "react";
import { ChatForm, type ChatFormProps } from "./ChatForm";

export type Message = {
  role: "user" | "assistant";
  content: string;
}

export function ChatApp() {
  const [messages, setMessages] = useState<Message[]>([]);
  const [isSending, setIsSending] = useState(false);

  const handleSendMessage = useCallback<ChatFormProps["onSendMessage"]>(
    async (message) => { 
      // We will implement this later
    }, []
  )

  return (
    <div>
      <ChatForm onSendMessage={handleSendMessage} isSending={isSending} />
    </div>
  )
}

Before implementing the send message logic, let's define how we want to display the messages.
Let's create a presentational component that renders a single message.

import type { Message } from "./ChatApp";

export type ChatMessageProps = {
  message: Message;
};

export function ChatMessage({ message }: ChatMessageProps) {
  return (
    <p>
     <span>From {message.role}:</span>
     <span>{message.content}</span>
    </p>
  )
}

Now let's define a component that will render a list of messages.

export type ChatLogProps = {
  messages: Message[];
};

export function ChatLog({ messages }: ChatLogProps) {
  return (
    <div role="log">
      {messages.map((message, i) => (
        <ChatMessage key={i} message={message} />
      ))}
    </div>
  );
}

Finally we can use the ChatLog component in our ChatApp component.

// ...
import { ChatLog } from "./ChatLog";

export function ChatApp() {
  // ...
  return (
    <div>
      <ChatLog messages={messages} />
      <ChatForm onSendMessage={handleSendMessage} isSending={isSending} />
    </div>
  )
}

Now it's time for the fun part. With Suspense we can easily render messages regardless of whether they are coming from the server or from the user. Let's define a MessageRenderer component that receives a message or a promise that resolves to a message.

import { use } from "react";
import { ChatMessage } from "./ChatMessage";

export type MessageRendererProps = {
  message: Message | Promise<Message>;
};

export function MessageRenderer(props: MessageRendererProps) {
  // Use will activate the suspense boundary when message is a promise
  const message =
    props.message instanceof Promise
      ? use(props.message)
      : props.message;

  return <ChatMessage message={message} />;
}

In the history component we can now use the MessageRenderer component to render messages.

import { Suspense } from "react";
import { MessageRenderer, type MessageRendererProps } from "./MessageRenderer";

export type ChatLogProps = {
  // Now both messages and promises are accepted
  messages: MessageRendererProps["message"][];
};

export function ChatLog({ messages }: ChatLogProps) {
  return (
    <div role="log">
      {messages.map((message, i) => (
        <Suspense key={i} fallback="Loading...">
          <MessageRenderer message={message} />
        </Suspense>
      ))}
    </div>
  );
}

While the message is loading, Suspense will render the fallback component. Once the promise resolves, the message will be rendered instead. To handle errors we need to wrap the Suspense element in an ErrorBoundary component.
I recommend using the react-error-boundary package for this.

npm install react-error-boundary
# yarn add react-error-boundary
# pnpm add react-error-boundary

We can render a fallback UI when an error occurs:

import { ErrorBoundary } from "react-error-boundary";

<ErrorBoundary fallback={<p>Error</p>}>
  <Suspense fallback="Loading...">
    <MessageRenderer message={message} />
  </Suspense>
</ErrorBoundary>

Let's create a component for the suspense fallback.
The fallback will receive a stream and will subscribe to it.
The component will listen to incoming tokens and aggregate them into a state called content. Every time content changes, a message prop is created and fed to ChatMessage.

export type MessageStream = ReadableStream<Uint8Array>

export type StreamingMessageProps = {
  stream: MessageStream;
};

export function StreamingMessage({ stream }: StreamingMessageProps) {
  const [content, setContent] = useState("");

  useEffect(() => {
    if (stream.locked) return;
    readMessageStream(stream, (token) => {
      // defined later
      setContent((prev) => prev + token);
    });
  }, [stream]);

  const message = {
    from: "assistant",
    content,
  };

  return (
    <ChatMessage message={message} />
  );
}

The StreamingMessage component will run until the server request promise is fulfilled. Then a regular ChatMessage will replace it, resulting in less memory consumption.

To read the stream i have created this utility function.
The stream is read asynchronously in a loop until the request completes. Then returns the full response as a concatenation of text chunks (tokens).

export async function readMessageStream(
  stream: ReadableStream,
  onNewToken: (token: string) => void = () => {},
) {
  const reader = stream.getReader();
  const decoder = new TextDecoder();
  const chunks: string[] = [];

  // eslint-disable-next-line no-constant-condition
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    if (value) {
      const chunk = decoder.decode(value);
      chunks.push(chunk);
      onNewToken(chunk);
    }
  }

  const text = chunks.join("");
  return text;
}

Now we can use the StreamingMessage component in our ChatLog component:

import { StreamingMessage, type MessageStream } from "./StreamingMessage";

export type ChatLogProps = {
  messages: MessageOrPromise[];
  stream?: MessageStream;
};

// ...
<ErrorBoundary fallback={<p>Error</p>}>
  <Suspense fallback={<StreamingMessage stream={stream} />}>
    <MessageRenderer message={message} />
  </Suspense>
</ErrorBoundary>

Now we can extend our ChatApp component to track the message stream and pass it to the ChatLog component.

// ...
import { ChatLog, type ChatLogProps } from "./ChatLog";
import { ChatForm, type ChatFormProps } from "./ChatForm";

export function ChatApp() {
  const [messages, setMessages] = useState<ChatLogProps["messages"]>([]);
  const [isSending, setIsSending] = useState<ChatFormProps["isSending"]>(false);
  const [stream, setStream] = useState<ChatLogProps["stream"]>();

  const handleSendMessage = useCallback<ChatFormProps["onSendMessage"]>(
    async (message) => { 
      // We will implement this later
    }, []
  )

  return (
    <div>
      <ChatLog messages={messages} stream={stream} />
      <ChatForm onSendMessage={handleSendMessage} isSending={isSending} />
    </div>
  );
}

Finally, here is the complete implementation of the handleSendMessage function:

const handleSendMessage = useCallback(
  (input: string) => {
    const userMessage: Message = {
      from: "user",
      content: input,
    }

    const assistantMessage = fetchMessageStream(input, sessionId)
      .then((stream) => {
        const [stream1, stream2] = stream.tee();
        setStream(stream1); // read by ChatLog
        return readMessageStream(stream2);
      })
      .then((text): Message => {
        return {
          from: "assistant",
          content: text,
        }
      });

    setIsSending(true);
    // Update messages state
    setMessages((prevMessages) => [
      ...prevMessages,
      userMessage,
      assistantMessage,
    ]);
  },
  [sessionId],
);


function fetchMessageStream(prompt: string, sessionId: string) {
  const response = fetch("/chat", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt,
      sessionId,
    }),
  });
  if (!response.ok) {
    throw new Error("Failed to fetch message stream");
  }
  return response.body satisfies ChatLogProps["stream"];
}

Better LLM Chatbots with React Suspense 🌀

Lorenzo Rivosecchi — Fri, 12 Jan 2024 13:09:50 +0000

AI Chatbots are a bit weird. When a user sends a message, its content is displayed instantaneously. In contrast, the chatbot's response requires an API request to be processed before any reply is displayed.

This imbalance can be a bit confusing to work with. Finding a way to handle both sync and async messages in a similar way is trivial. Thankfully, with Suspense we can do it with ease.

The solution I'm proposing depends on some features that have not been released on a stable version of React yet. Use at your own risk.

Let's start by defining a Message type:

type Message = {
  from: "user" | "bot";
  id: string;
  content: string;
}

Pretty straightforward. Now, since the bot message will be created asynchronously, we can use a Promise to represent it. Let's then declare a Messages type that will inform our application about that messages could be either a message or a promise that resolves to a message:

type Messages = Array<Message | Promise<Message>>;

Then, let's create a simple component that contains a form that allows the user to send a message:

function Chatbot() {
  const [input, setInput] = useState("");
  const [messages, setMessages] = useState<Messages>([]);

  const handleSubmit = useCallback<FormEventHandler<HTMLFormElement>>(
    (e) => {
      e.preventDefault();
      // 1. Create message with the user's input
      // 2. Create a promise that resolves to the bot's response
      // 3. Update messages state to include both messages
    },
    [setMessages, input]
  );

  return (
    <div>
      <form onSubmit={handleSubmit}>
        <input type="text" value={input} onChange={handleInputChange} required />
        <button type="submit">Send</button>
      </form>
      {/* the messages will be rendered here below */}
    </div>
  )
}

Now, let's complete the body of the handleSubmit function:

Step 1 is easy, we just need to create a Message with the user's input:

// 1. Create message with the user's input
const userMessage: Message = {
  from: "user",
  id: Date.now().toString(),
  content: input,
};

Step 2 requires a bit more work. We need to create a function that will fetch the bot's response. For the sake of simplicity, let's just create a function that returns a promise that resolves to a string:

async function fetchResponse(message: string): Promise<string> {
  return new Promise((resolve) =>
    setTimeout(() => {
      console.log("Message sent:", message);
      resolve("I don't know");
    }, 1000)
  );
}

Then, we can use this function to create a promise that resolves to a Message with the bot's response:

// 2. Create a promise that resolves to the bot's response
const botMessage: Promise<Message> = fetchResponse(input).then((response) => ({
  from: "bot",
  id: Date.now().toString(),
  content: response,
}));

Finally, we can add both messages to the state:

// 3. Update messages state to include both messages
setMessages((messages) => [
  ...messages, userMessage, botMessage
]);

Now let's see how we can render the messages. In our JSX we render all the message wrapped in a Suspense component:

function ChatBot() {
  const [messages, setMessages] = useState<Messages>([]);
  // ...
  return (
    // ...
    <div role="log">
      {messages.map((message, index) => (
        <Suspense key={index} fallback="Loading...">
          <MessageRenderer message={message} />
        </Suspense>
      ))}
    </div>
  )
}

The MessageRenderer component receives a prop called message that can be an actual message or a promise that resolves to a message. When the message is a promise, we need to inform the Suspense component that it should wait for the promise to resolve before rendering the message. We can do that by wrapping the message prop with the use hook.

As of January 2024 this hook is only available in the canary version of React. Refer to the docs to understand how to use it.

/// <reference types="react/canary" />
import { use, /* ... */ } from "react";

function MessageRenderer({ message }: { message: Message | Promise<Message> }) {
  // the use hook can be called conditionally
  const { from, content } = message instanceof Promise ? use(message) : message;
  return (
    <div>
      <p>From: {from}</p>
      <p>{content}</p>
    </div>
  );
}

Now, let's finish this by adding error handling. To do it you simply need to wrap the Suspense component with an ErrorBoundary and provide a fallback component that will be rendered when an error occurs:

// ...
import { ErrorBoundary } from "react-error-boundary";

function ChatBot() {
  // ...
  return (
     // ...
    <div role="log">
      {messages.map((message, index) => (
        <ErrorBoundary fallbackRenderer={ErrorRenderer}>
          <Suspense key={index} fallback="Loading...">
            <MessageRenderer message={message} />
          </Suspense>
        </ErrorBoundary>
      ))}
    </div>
  )
}

// ...

function ErrorRenderer({ error }) {
  return (
    <div role="alert">
      <p>{error instanceof Error ? error.message : "Something went wrong"}</p>
    </div>
  )
}

And that's it! You can check the full code here.

This approach works with streaming as well. I can't speak for performance or potential leaks, but after some brief testing I didn't notice any issues.
The idea is to pass a ReadbleStream to the Suspense fallback element and render incoming chunks as they arrive.

You can check the streaming version of the app at this link.

I Published my CV on NPM 🤖

Lorenzo Rivosecchi — Fri, 29 Dec 2023 15:51:35 +0000

A few months ago I decided to refresh my old CV made with Pages to something more personal. I decided that, since I'm a developer, it would be fun if my CV was generated from code. As many of my side projects go, I started with a simple idea, end I ended up with a riduculous overengineered solution that lead me to publishing the curriculum as an NPM package.

If you want to skip the story and see the result, run the following command:

npx @fibonacid/curriculum@latest
# pnpm dlx @fibonacid/curriculum@latest

If you just want to read the CV, you can see the web version here.

Writing

The CV is written inside the README.md file of the project.
It's a simple markdown file that contains the usual sections of a CV: personal info, education, work experience, skills, etc.

# Lorenzo Rivosecchi

I'm a Web Developer with 5 years of experience in the field. I'm currently working at [Assist Digital](https://assistdigital.com) as a Frontend Developer.
I have a background in Computer Music and my passions are music, technology and design.

[![Github](https://img.shields.io/badge/Github-black?logo=github)](https://github.com/fibonacid)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?logo=linkedin)](https://www.linkedin.com/in/lorenzo-rivosecchi/)
[![Blog](https://img.shields.io/badge/Blog-black?logo=devdotto)](https://dev.to/fibonacid)
[![X (formerly Twitter)](https://img.shields.io/twitter/follow/fibonacid)](https://twitter.com/fibonacid)

Rendering

To render the file I used unified, with the following plugins:

import rehypeFormat from "rehype-format";
import rehypeStringify from "rehype-stringify";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import remarkGfm from "remark-gfm";

const processor = unified()
  .use(remarkParse)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeDocument)
  .use(rehypeFormat)
  .use(rehypeStringify);

The README.md is read and processed, then written to a file inside the dist folder.

import { readFile, writeFile } from "node:fs/promises";

// Read the file and process it
const input = await readFile("README.md");
const file = await processor.process(input);

// Write the file to disk
const output = String(file);
await writeFile("dist/index.html", output);

PDF Generation

Since most job applications require a PDF version of the CV, I decided to use Puppeteer to generate it.

import puppeteer from "puppeteer";

// Launch the headless browser and open a new page
const browser = await puppeteer.launch({
    headless: "new",
});
const page = await browser.newPage();

// Navigate to the generated HTML file and generate the PDF
await page.goto(`file://${process.cwd()}/dist/index.html`);
await page.pdf({
    path: "./dist/Curriculum.pdf",
    format: "A4",
});

Now i can execute the build script to get the PDF version:

{
  "scripts": {
    "build": "node build.js"
  }
}

To make sure that the PDF is always up to date, I added a pre-commit hook that runs the build script before every commit.

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

yarn build

Styling

Since the README looked pretty good on Github, I decided to make my CV look exactly like that. Thankfully I found a package called generate-github-markdown-css that made it easy to grab the original CSS from Github and use it in my project.

import githubMarkdownCss from 'generate-github-markdown-css';
import fs from "node:fs/promises";

async function main() {
  const css = await githubMarkdownCss({
    rootSelector = 'body',
  });
  await fs.writeFile("./assets/style.css", css);
}

To use the CSS in my HTML i just need to add it to the head of the document using rehype-document:

const processor = unified()
  // other plugins
  .use(rehypeDocument, {
    css: "./assets/style.css",
    style,
  })

Publishing

Since this CV will be distributed as a PDF, I need an automatic way to build and publish it somewhere for easy access. My first idea was to use Github Actions to build the pdf and upload it to a Google Drive folder, but the GDrive API is a bit of a pain to use, so I decided to publish it on NPM instead.

At this point I thought the work was almost done. My original idea was to let people download my CV using this commad:

npm install @fibonacid/curriculum

And include a postinstall script that would open the PDF in the browser:

{
  "scripts": {
    "postinstall": "open node_modules/@fibonacid/curriculum/dist/Curriculum.pdf"
  }
}

This doesn't work for some reason, therefore I decided to create a simple CLI script that would ask the user where they want to store the file and if they want to open it immediately.

const answers = await inquirer.prompt([
    {
      type: "input",
      name: "folder",
      message: "Where should I save the file?",
    },
    {
      type: "input",
      name: "filename",
      message: "How should I name the file?",
    },
    {
      type: "confirm",
      name: "open",
      message: "Do you want to read it now?",
    },
  ]);

To expose the CLI I just needed to add a bin field to the package.json file:

{
  "bin": "./cli.js"
}

And that's it! Now I can publish my CV on NPM and let people download it with a simple command.

npx @fibonacid/curriculum

Need to install the following packages:
  @fibonacid/curriculum
Ok to proceed? (y) y

? Where should I save the file? /Users/lorenzo/Downloads
? How should I name the file? Curriculum.pdf
? Do you want to open the file? (Y/n) y

Conclusion

This project was a lot of fun to build and I learned a lot of new things. I'm excited to build more stuff with Markdown and unified in the future. If you want to check out the full code, you can find it here

Creating a TODO app using the HTML dialog element

Lorenzo Rivosecchi — Mon, 20 Nov 2023 14:06:32 +0000

In a previous article i have shown how to use the HTML dialog element with React. Since then I have found a better solution. Let's dive into it.

TODO App

Let's build a todo app with a list of todos and a button to generate a new todo. The todo will be generated in a dialog element.

import { useState } from "react";
import Dialog, { DialogProps } from "./Dialog";

const initialTodos = [
  "Write a blog post",
  "Share the article",
  "Find mistakes",
  "Write new article",
];

export default function App() {
  const [todos, setTodos] = useState<string[]>(initialTodos);
  const [open, setOpen] = useState(false);

  return (
    <main className="m-4">
      <h1 id="title" className="text-lg font-bold mb-2">
        TODOs
      </h1>
      <ul aria-labelledby="title" className="list-disc list-inside mb-4">
        {todos.map((todo) => (
          <li key={todo}>{todo}</li>
        ))}
      </ul>
      <button
        onClick={() => setOpen(true)}
        className="bg-black text-white p-2 rounded"
      >
        Add todo
      </button>
    </main>
  );
}

Nothing remarkable here. Let's add the dialog element.
We are going to create a Dialog component with the bare minimum to make the element play nice with React.

Let's start with the props:

export type DialogProps = Omit<
  ComponentPropsWithoutRef<"dialog">,
  "onClose"
> & {
  open: boolean; // required
  onClose: (returnValue?: string) => void; // override
};

We want to extend the native dialog props with some modifications:
The open prop should be required, signaling that the dialog needs to be controlled by the parent component.
A similar thing needs to happen with the onClose method: Instead of passing the event, which is not very useful, we can pass the return value of the dialog.

Now let's create the component:

export default function Dialog(props: DialogProps) {
  const { open, children, onClose, ...rest } = props;
  const dialogRef = useRef<HTMLDialogElement>(null);

  useEffect(() => {
    if (open) {
      dialogRef.current?.showModal();
    } else {
      dialogRef.current?.close();
    }
  }, [open]);

  const handleClose = useCallback(() => {
    onClose(dialogRef.current?.returnValue);
  }, [onClose]);

  return (
    <dialog ref={dialogRef} onClose={handleClose} {...rest}>
      {children}
    </dialog>
  );
}

Now we can use the dialog in our app.
Let's create a new component called CreateTodo:

import { useState } from "react";
import Dialog, { DialogProps } from "./Dialog";

export function CreateTodo({
  open,
  onClose,
}: Pick<DialogProps, "open" | "onClose">) {
  const [value, setValue] = useState("");
  return (
    <Dialog
      open={open}
      onClose={onClose}
      aria-labelledby="todo-title"
      aria-describedby="todo-description"
      className="rounded mt-10 p-4"
    >
      <h3 id="todo-title" className="font-bold text-lg mb-2">
        Create TODO
      </h3>
      <p id="todo-description" className="mb-2">
        Enter the name of the TODO
      </p>
      <form method="dialog">
        <div className="mb-4">
          <label htmlFor="todo-name" className="sr-only">
            TODO
          </label>
          <input
            id="todo-name"
            className="border rounded p-1 w-full"
            value={value}
            autoFocus
            onChange={(e) => {
              setValue(e.target.value);
            }}
          />
        </div>
        <div className="flex gap-2">
          <button formMethod="dialog" className="flex-1 rounded border p-2">
            Cancel
          </button>
          <button
            value={value}
            disabled={!value}
            className="flex-1 rounded border p-2 bg-black text-white disabled:opacity-50"
          >
            Add
          </button>
        </div>
      </form>
    </Dialog>
  );
}

This component wraps the Dialog component we just created and adds the necessary markup and logic to create a new todo. Let's dissect it:

<form method="dialog">{/* ... */}</form>

This form is essential to make the dialog work. It uses the method attribute to tell the browser to close the dialog when the form is submitted.

<input
   id="todo-name"
   className="border rounded p-1 w-full"
   autoFocus
   onChange={(e) => setValue(e.target.value)}
   value={value}
/>

This input is necessary to register the return value of the dialog. The autoFocus attribute is there to make sure the input is focused when the dialog opens.

<div className="flex gap-2">
  <button formMethod="dialog" className="flex-1 rounded border p-2">
    Cancel
  </button>
  <button
    value={value} // value from the input
    disabled={!value}
    className="flex-1 rounded border p-2 bg-black text-white disabled:opacity-50"
  >
    Add
  </button>
</div>;

These buttons are the ones that will close the dialog. The first one uses the formmethod attribute to tell the browser to close the dialog without returning a value. The second one uses the value attribute set its state the the value of the input. When the dialog closes, the browser will set the returnValue property of the dialog to the value of the button.

Since in our Dialog component we have overridden the onClose method, we can get the return value from the App component as follows:

export default function App() {
  const [todos, setTodos] = useState<string[]>(initialTodos);
  const [open, setOpen] = useState(false);

  return (
    <main className="m-4">
      {/* ... */}
      <button
        onClick={() => setOpen(true)}
        className="bg-black text-white p-2 rounded"
      >
        Add todo
      </button>
      <CreateTodo
        open={open}
        onClose={(value) => {
          setOpen(false);
          if (value) setTodos([...todos, value]);
        }}
      />
    </main>
  );
}

And that's it! You can find the full code here

Taming the HTML dialog with React and TailwindCSS

Lorenzo Rivosecchi — Wed, 01 Nov 2023 18:26:14 +0000

Today, we're going to create a modal component using HTML's native dialog element, along with React and TailwindCSS.

To see it in action, visit this link.

If you'd like to try out my implementation, you can find it in the GitHub Repository or download the component using this command:

npx degit \
   fibonacid/html-dialog-react-tailwind/src/Step3.tsx \
   ./Modal.tsx

Make sure you have TailwindCSS configured and tailwind-merge installed as a runtime dependency in your project. Let's get started!

Step 1: Wrap the HTML Dialog Element

Working with the HTML dialog element can be a bit tricky. It's a good practice to create a wrapper for it, providing a declarative API for ease of use. Let's begin by simply wrapping the element and passing all its properties through:

// components/Modal.tsx
import { type ComponentPropsWithoutRef } from "react";

export type ModalProps = ComponentPropsWithoutRef<"dialog">;

export default function Modal(props: ModalProps) {
  return (
    <dialog {...rest}>
      {children}
    </dialog>
  );
}

In the HTML dialog element's documentation, you'll find it has an open attribute. Naturally, you might think to use this with React to control the modal's visibility. However, it's not that straightforward. Using the following code reveals that once opened, the modal can't be closed:

import { useState } from "react";
import Modal from "./components/Modal";

export default function App() {
  const [open, setOpen] = useState(false);

  return (
    <div>
      <button
        className="m-4 underline outline-none focus-visible:ring"
        onClick={() => setOpen(true)}
        aria-controls="modal"
        aria-labelledby="modal-title"
        aria-describedby="modal-desc"
      >
        Open modal
      </button>
      <Modal id="modal" open={open} onClose={() => setOpen(false)}>
        <h2 id="modal-title" className="mb-1 text-lg font-bold">
          Modal
        </h2>
        <p id="modal-desc">
          Lorem ipsum dolor, sit amet consectetur adipisicing elit. Ab optio
          totam nihil eos, dolor aut maiores, voluptatum reprehenderit sit
          incidunt culpa? Voluptatum corrupti blanditiis nihil voluptatem atque,
          dolor ducimus! Beatae.
        </p>
        <button
          autoFocus={true}
          className="float-right underline outline-none focus-visible:ring"
          onClick={() => setOpen(false)}
          aria-label="Close modal"
        >
          Close
        </button>
      </Modal>
    </div>
  );
}

The open attribute is intended for reading the dialog's state, not setting it. To open and close the dialog, we must use the showModal and close methods:

const dialog = document.querySelector('dialog');

dialog.showModal();
console.log(dialog.open); // true

dialog.close();
console.log(dialog.open); // false

To synchronize the dialog's state with React, we'll use a useEffect hook. It will listen for changes to the open prop and call the showModal and close methods accordingly:

// components/Modal.tsx
import { useEffect, useRef, type ComponentPropsWithoutRef } from "react";

export type ModalProps = ComponentPropsWithoutRef<"dialog"> & {
  onClose: () => void;
};

export default function Modal(props: ModalProps) {
  const { children, open, onClose, ...rest } = props;
  const ref = useRef<HTMLDialogElement>(null);

  useEffect(() => {
    const dialog = ref.current!;
    if (open) {
      dialog.showModal();
    } else {
      dialog.close();
    }
  }, [open]);

  return (
    <dialog ref={ref} {...rest}>
      {children}
    </dialog>
  );
}

If you rerun the code in App.tsx, the modal now behaves as expected. However, there's still an issue. If you open the modal and then press , it closes, but the React state isn't updated. Consequently, clicking the open button again won't re-trigger the effect, and the modal won't open. To address this, we need to listen to the dialog's close and cancel events, updating the state accordingly:

useEffect(() => {
  const dialog = ref.current!;
  const handler = (e: Event) => {
    e.preventDefault();
    onClose();
  };
  dialog.addEventListener("close", handler);
  dialog.addEventListener("cancel", handler);
  return () => {
    dialog.removeEventListener("close", handler);
    dialog.removeEventListener("cancel", handler);
  };
}, [onClose]);

With these changes, our modal component should now be fully functional.

Step 2: Style the Modal

Now that our dialog is functional, let's enhance its appearance with TailwindCSS. We'll modify the Modal component to apply a default set of styles, which can be extended by users through the className property:

// same imports...
import { twMerge } from "tailwind-merge";

// same type...

export default function Modal(props: ModalProps) {
  const { children, open, onClose, className, ...rest } = props;

 // same hooks...

  return (
    <dialog ref={ref} className={twMerge("group", className)} {...rest}>
      <div className="fixed inset-0 grid place-content-center bg-black/75">
        <div className="w-full max-w-lg bg-white p-4 shadow-lg">{children}</div>
      </div>
    </dialog>
  );
}

Two important aspects to note here:

We're using the twMerge function from the tailwind-merge package to combine the default styles with those specified by the user.
We are using divs to render the backdrop and the modal container instead of using the ::backdrop pseudo-element. This is because styling the dialog element itself is tricky, especially when it comes to CSS Transitions.

Step 3: Animate the Modal

Animating a modal component using the HTML <dialog> element can be somewhat complex. A key challenge arises because when this element is closed, browsers automatically apply a display: none style. This style interferes with the smooth application of CSS transitions and animations.

To work around this, we need to manage the timing of applying the open property. It's important to delay its application until the enter/exit transitions are complete. For this, we'll use a data-open attribute. This attribute allows us to toggle between open and closed states without activating the display: none style.

Here's how we can update the useEffect hook to handle this:

useEffect(() => {
  const dialog = ref.current!;
  if (open) {
    dialog.showModal();
    dialog.dataset.open = "";
  } else {
    delete dialog.dataset.open;
    const handler = () => dialog.close();
    const inner = dialog.children[0] as HTMLElement;
    inner.addEventListener("transitionend", handler);
    return () => inner.removeEventListener("transitionend", handler);
  }
}, [open]);

For applying transitions, we can use a TailwindCSS class named group. This class enables us to apply conditional styles to the children of our dialog component effectively. Here’s how to integrate it:

<dialog ref={ref} className={twMerge("group", className)} {...rest}>
  <div className="fixed inset-0 grid place-content-center bg-black/75 opacity-0 transition-all group-data-[open]:opacity-100">
    <div className="w-full max-w-lg scale-75 bg-white p-4 opacity-0 shadow-lg transition-all group-data-[open]:scale-100 group-data-[open]:opacity-100">
      {children}
    </div>
  </div>
</dialog>

This approach will help in creating a smooth, visually appealing transition for your modal.