Tim's Tech Blog

React Server Components, without a framework?

2023-11-07T00:00:00+00:00

Introduction #

React Server features, concepts & APIs, in particular React Server Components & React Server Actions have been in the spotlight for the past week, following recent announcements by the React Team (React Server & Client Actions on October 23rd) & Next.js - Next.js 14 “Server Actions (stable)” announced on October 26th 2023 at Next.js Conf - which had a very strong resonance in tech communities & on social media.

Before then, I was somewhat oblivious to the RSC model, and upcoming React Canary features.

Sure, over the years, I had heard & thought quite a bit about the possibilities of a React putting a stronger focus on the server, especially when I was working at Gandi for 6 years, where we had been working with React since ~v0.13.0 / 2015, building our own, in-house, custom React / Redux isomorphic / universal SPA / SSR full-stack framework, architecture & ecosystem powering ~10 business-critical production applications.
I had also dipped a toe in the mozilla/addons-frontend code base of Mozilla Addons marketplace (AMO), which leverages a comparable architecture, from the same era.

Despite the years, the distance & perspective I now have from my old job at Gandi (I left in 2020 after 6years), the technical challenges related to my experience, striving to build a performant, resilient, capable, productive, tailored, in-house React framework with progressive enhancement and no-js first-class support (essentially what meta-frameworks such as Remix, Next.js & maybe others can do today if you're serious about it), have been living rent-free in my head ever since (and I have many more like that, such as when to use React.memo).

So of course, when I saw on Twitter the RSC / React Canary / Server & Client Actions announcements mentioned earlier, I was excited!
Could it be? A React-native, official first-party solution to all the problems of React server-side rendering: data-fetching, waterfall, routing, latency, partial / selective hydration, in-or-out-of-order streaming, you name it: maybe that was it.

And so, I began an unreasonable journey, starting to look into React Server APIs, the RSC model, Client / Server actions, React Canary, etc. from scratch, with close to zero prior knowledge, and a lot of interrogations.

RSC Survival Guide #

Before going any further, chances are the average reader is as confused about all this as I was when I first started looking into this a few days ago.
Indeed, X dot com is full of keywords, code snippets, memes & engagement baits while actual information regarding this topic is scattered, incomplete, missing, tied to a specific Meta-framework, focused on high level use cases, or simply slightly harder to find than the typical React content covering mature & stable patterns, such as React controlled inputs - ok that's the last internal backlink, I Promise concurrently.

Disclaimer #

This section aims to serve as a quick reference for RSC, centralizing what I consider to be the most important terms, definitions & concepts about these features, just so a maximum amount of readers who made it this far (thank you! means a lot to me) can follow along with the rest of the blog post.

The goal is not to provide a guide on how to use these features, rather an extract & structuring of my personal understanding of the different pieces of the puzzle based on my personal research, with links to relevant resources.

Please bear in mind this blog post mentions experimental & under-documented features & APIs and generally covers a complex & continously-evolving topic - it may not be the best source of information for beginners or readers who have never yet been exposed to the concepts of the RSC Model.

THE BLOG POST IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED…

React Client Components #

React Client Components are traditional React Components - which can run on the client, traditionally the browser.
Chances are, most of the React components you've ever been in contact with and that you're used to, at least prior to React 18 & Next.js 13 were Client Components, and this, regardless of them being rendered by React DOM Server APIs to produce or stream HTML for server-side rendering (SSR) or build-time static site generation (SSG).

“The name “Client Component” doesn’t mean anything new, it only serves to distinguish these components from Server Components”

“If you have an existing client-side app, you can think of all of it as a Client Component tree”

RFC: React Server Components #188

The React Server Components Model #

React Server Components Announcements Timeline #

React Server Components #

React Server Components, strictly speaking, are React components that run exclusively on the server, they never run or are even hydrated on the client, in fact, aren't even included, bundled with alongside client-side code, and thus have no client-side JavaScript bundle size impact.

However, and even more importantly:

“Server Components allows the server and the client (browser) to collaborate in rendering your React application.
Consider the typical React element tree that is rendered for your page, which is usually composed of different React components rendering more React components.
RSC makes it possible for some components in this tree to be rendered by the server, and some components to be rendered by the browser.”

RFC: React Server Components #188

A quick note on “React SSR” #

It's important to note that RSC is different than “React SSR”.
Without diving in a “RSC vs React SSR” comparison, I'll just mention a few points:

(React) “SSR” is most commonly used to refer to the rendering on the server of a tree of React components to inert, non-interactive HTML to serve a page's initial load, the same components tree which is then potentially hydrated in the client to enable interactivity
RSCs, on the other hand, are not rendered to HTML, but to a JSON-like format.

In the RSC paradigm, all components are Server Components by default.
However, since an instance of a Server Component runs only once, Server Components can only use a subset of React Component APIs, and can't use client-only APIs such as React.useState / React.useReducer (same thing), React.useEffect, Context.Provider etc.

Furthermore Server Components cannot be directly imported nor rendered by Client Components.
But their serialized render output can be fetched at the server from the client & inserted in within a client-side components tree.

Server Components also cannot render Client Components, but they can pass serializable props to them - by “serializable” props, we mean JavaScript data types such as simple objects, arrays, strings, numbers, as well as Promises wrapping such data types, but not functions & classes for example.

React Shared Components #

React Shared Components are “neutral” components: they can be both Server Components & Client Components - not using either of client or server specific features & APIs.
As such, a given Shared Component in a React components subtree ultimately ends being either a Server Component or a Client Component, depending on the parent context in which they are rendered:

a shared component becomes a server component when it is rendered with React Server APIs or from a server component

and conversely:

a shared component becomes a client component when it is rendered with React DOM APIs, or from a client component

Plot twist: components can be marked client-only using the 'use client' directives.

`'use server'` & `'use client'` directives #

Although they look similar to the standard, runtime 'use strict' directive, 'use server' & 'use client' are specific to React and don't do anything by themselves or at runtime: today they're build-time hints for the bundler (or equivalent tooling) to consider the marked modules as a boundary between server & client in the module dependency tree.

Note: I'm not going into more details about these directives here, because the official documentation is already really good at the time of writing, and paraphrasing doesn't bring more value.
There are a couple of caveats / subtleties that aren't necessarily covered in the official documentation, but mentioning them at this point of the blog post I think would only risk additional confusion.
But we'll get back to these directives further in the blog post.

`'use client'` #

'use client' is primarily used to mark a specific component as being client-only, including all of its components subtree.
See 'use client' official React documentation.

`'use server'` #

See 'use server' official React documentation.

Suspense & Error Boundaries #

The RSC Model leverages existing Stable React APIs such as Suspense & Error Boundaries, these two APIs in fact play an central role in the RSC Paradigm, alongside the use() hook, a new React Experimental API.

`use()` #

I'll just mention that the use() hook enables dealing with Promises inside React Components.
This is over-simplified, and we'll see in more concrete terms how to use them further in the blog post.

See use() hook React Experimental API official documentation.

Demo: migrating a React Notes App to RSC without a framework #

A take-home technical assignment backstory #

In 2020, while looking for my next job, I was contacted by a well known tech company regarding a remote-friendly open position, which really resonated with my interests and I was thrilled at the opportunity.
The hiring process required to complete a take-home technical exercise - although I'm really not a fan of this hiring practice, on either side of the table - I decided that I would try.

A React Notes App (2020) #

The assignment was essentially: build a React Notes App, and then some functional UI requirements.

And so I started working on building the following React Notes App with Create React App, documenting my process on Twitter & publishing the code on GitHub.

Notes:

while this app still holds up fairly well in my opinion, it is far from perfect, especially by today's standards.
you may notice that the hosted version while functionally identical to the source code in the repository, has been optimized for bundle size, most notably by fine-tuning the Babel configuration & aliasing React to Preact: from 161KB (according to my notes, I haven't been bothered to run the project again locally but the details are somewhere in the ~live-tweeting) to 38.5 kB (uncompressed production build).

To wrap this up, let's just say the hiring team was pleased with my work, everything was going well after that, until the recruiter asked me if I was willing to relocate to another country (despite being clear about working remotely from France - at absolute peak COVID-19 times - and having spent many hours working on the assignment).
Ironically, it was only after I had already accepted an offer at Dashlane that the first company reached back to me & suggested starting out remotely as a contractor.

Ok, ok, but what does it all have to do with Server Components?

Well I've lately been using it this notes app as a playground for experiments & side projects.
So naturally, when I started looking into RSC last week, I thought to myself:

why not try to see to which extent I can naively migrate this simple notes app to RSC without a framework?

Actually migrating a CRA React Notes App to RSC with no framework (2023)

No framework? Really?
Yes! Really! It's an experiment! It's fun!
And it's a great way to understand how things work, as well as illustrating the value of a "real" framework.
That being said, I am a huge supporter of building your own production framework for "real world" applications if you have the opportunity, the resources and can justify it to address your use cases, it'll just need to go much further than what is described in this blog post, more on this later.

Disclaimer #

Please note, there is absolutely nothing optimal about the following implementation, it is purposely naive, incomplete, and is intended for learning & demo purposes.

Inspiration #

Our demo is inspired by React Team react server components demo from December 2020.
The idea was not to re-create the demo above, or to create as good a showcase of RSC, rather to try & use RSC features & APIs in an existing app.
We will be borrowing some code patterns, with varying degrees of correctness & success.
I also invite you to take a look at the official demo linked above & related materials.

RSC Notes App Demo / Playground #

Objectives #

a somewhat functional React Notes App (listing, creating, editing & deleting notes with a text title & Markdown content)
React Server Components used alongside Client Components
some sort of server-side rendering
some kind of data-fetching using Server Components
routing that somewhat works both in the client & on the server
refreshing server components from the client
a usable RSC playground
above all else: learn

Dependencies #

node v18.8.1 & npm v9.8.1
Fastify for the HTTP web server
Webpack bundler
Babel JavaScript compiler, for transpiling JSX syntax
a-route extremely minimal JavaScript / DOM routing library leveraging Custom Elements (also used in our original React Notes App)

React Canary #

At the time of writing, the latest React Canary release is 18.3.0-canary-8039e6d0b-20231026.
We need to use the same version for the react & react-dom packages.

// package.json
"dependencies": {
  ...
  "react": "^18.3.0-canary-8039e6d0b-20231026",
  "react-dom": "^18.3.0-canary-8039e6d0b-20231026",
  ...
}

React Server & React Flight APIs #

The traditional React dependencies are no longer sufficient when it comes to using Server Components, and for 'use client' directives to play their role. For this, specialized tooling is required, and we're only interested in using what is provided by the React Team.

Like the official RSC demo we've mentioned earlier, we will be relying on the react-server-dom-webpack package to enable RSC features.

"Experimental React Flight bindings for DOM using Webpack - Use it at your own risk".

Note: These APIs are completely undocumented and there might be better alternatives, provided by the React Team or otherwise.

In particular, we will be using the following APIs, which I've done my best to succintly describe:

`react-server-dom-webpack/plugin` #

react-server-dom-webpack/plugin is a Webpack Plugin to:

generate the client chunks based on the presence of the 'use client' directive within modules.
reference the client chunks & the other chunks they depend on in a react-client-manifest.json file.
leverage Webpack's runtime to load the client chunks on demand: code splitting.

Example Usage #

// webpack.config.js
const ReactServerWebpackPlugin = require("react-server-dom-webpack/plugin");

return {
    ...
  plugins: [
    ...
    new ReactServerWebpackPlugin({ isServer: false }),
  ],
}

{
  // react-client.manifest.json
  ...
  "file:///rsc-no-framework-demo/src/app/tabs.jsx": {
    "id": "./src/app/tabs.jsx",
    "chunks": [
      "client5",
      "client5.chunk.js"
    ],
    "name": "*"
  }
}

`react-server-dom-webpack/node-register` #

react-server-dom-webpack/node-register, to create client & server references at runtime on the Node.js server, and creating proxies for client modules. This what effectively enables React Server Components to pass props to Client Components.

Example Usage #

// server entry-point
const reactServerRegister = require("react-server-dom-webpack/node-register");
reactServerRegister();

`renderToPipeableStream` from `react-server-dom-webpack/server` #

react-server-dom-webpack/server#renderToPipeableStream, renders a provided React Element with a Server Components subtree to an object matching a PipeableStream interface & returns it, allowing the consumer to pipe it to a WritableStream. This is what effectively renders React Server Components to the React Flight format & allows the output to be streamed to the client over HTTP.

Example Usage #

// server.js

const MANIFEST = readFileSync(
  path.resolve(__dirname, "../dist/react-client-manifest.json"),
  "utf8"
);
const MODULE_MAP = JSON.parse(MANIFEST);

function renderReactTree(writable, component, props) {
  const { pipe } = renderToPipeableStream(
    React.createElement(component, props),
    MODULE_MAP
  );
  pipe(writable);
}

...

// streaming the rendering output of the App element & its RSC subtree
// to the React Flight format in a Fastify route handler
reply.header("Content-Type", "application/octet-stream");
renderReactTree(reply.raw, App, props);

...

// accumulating to a string the rendering output of the App element & its RSC subtree
let flightResponse = "";
const flightStream = new stream.Writable({
  write: (chunk, encoding, next) => {
    flightResponse += chunk;
    next();
  },
});
renderReactTree(flightStream, App, props);

await finished(flightStream);

`createFromReadableStream` from `react-server-dom-webpack/client` #

react-server-dom-webpack/client#createFromReadableStream is essentially a wrapper around React Flight Client API.

This is an experimental package for consuming custom React streaming models.
Its API is not as stable as that of React, React Native, or React DOM, and does not follow the common versioning scheme.
Use it at your own risk.

Provided with a ReadableStream of React Flight serialized Server Components data, it outputs a Thenable, essentially reading & wrapping the data chunks in a Promise-like data structure, which can be consumed by APIs dealing with Promises, essentially the use() experimental hook.
This is the main RSC API that allows for React Server Components tree output computed on the server and serialized to the React Flight format to be rendered on the client.

Example Usage #

import { createFromReadableStream } from "react-server-dom-webpack/client";

...

const flightTreePromise = createFromReadableStream(
  // fake a ReadableStream with the Response constructor
  new Response(flightResponseText).body
);

`createFromFetch` from `react-server-dom-webpack/client` #

react-server-dom-webpack/client#createFromReadableStream is essentially a wrapper around createFromReadableStream from react-server-dom-webpack/client, unwrapping the Response promise to retrieve the underlying ReadableStream.
It serves the same purpose, but allows for the most common React Flight Client use case: rendering streamed React Server Components serialized output elements on the client, from a single fetch call.

Example Usage #

const [flightTreePromise, setFlightTreePromise] = useState(
  initialFlightTreePromise
);

...

const refreshFlightTreePromise = createFromFetch(
  fetch(
    `/react-flight?props=${encodeURIComponent(JSON.stringify(props))}`
  )
);

setFlightTreePromise(refreshFlightTreePromise);

...

return use(flightTreePromise);

Our first React Server Component #

In this hypothetical example, <App /> and all its subtree are Shared Components.
They do not use any client-specific APIs, they can be both Server Components or Client Components, they can be both rendered on the server or on the client.

export function App() {
  const items = [];

  return (
    <Layout header={<Header />}>
      <List items={items} />
    </Layout>
  );
}

Because we will be rendering the <App /> component and its subtree with React Server APIs, all these components are automatically Server Components.
The rendering of the <App /> component, even though it is streamed, can be considered synchronous: a single React Flight chunk is emitted.

Server-Side Rendering of Server Components #

React Server & React Flight APIs being completely undocumented as mentioned earlier, properly rendering output of React Server Components to HTML, and streaming it efficiently to the browser, without a framework, is quite challenging.
Indeed, while it is relatively straightforward to obtain the rendering output of a server components tree in the React Flight Format (also known as the RSC payload), as a PipeableStream or a string using these APIs - renderToPipeableStream in particular - at the time of writing, I don't know how to efficiently translate it to HTML - and I was too lazy to deep dive in Next.js' implementation.
But for the purposes of learning & demonstration, we really want to do something, anything that ressembles Server Components SSR.

An Unorthodox SSR Implementation #

Traditional SSR Store Serialization #

Traditionally, one way of doing React SSR is to fetch necessary data prior to or while rendering the application, using React DOM Server APIs, such as ReactDOM.renderToString().
As the data is fetched, it populates a store such as a Redux store.

Once the rendering of the application is completed, the Redux store is serialized to JSON, so it can be used as the client-side application's store initial state.
In order to be picked up when the client application loads, the serialized store output is generally included at the end of the HTML document, as a JSON string inside a <script> tag, or as a string or assigned directly to a variable with const state = JSON.parse('{serialized_store}').
This is necessary to correctly hydrate the sever-side rendered React tree, allowing client-side React to re-run the components tree with the same data used for the server-side rendering.

Server Components React Flight Output Serialization #

As Server Components are rendered to the serialized React Flight format, we can apply the same technique to the RSC payload.
Of course, this is incredibly suboptimal, and eliminates most of the benefits of Server-side rendering.

We actually shouldn't even call it Server-side rendering, because the Server components tree is not even rendered as HTML in the served initial HTML document, and JavaScript is necessary to render the RSC tree into the DOM.

But regardless, this still has some benefits: we don't have to make one extra Fetch HTTP request when the client-side app loads to retrieve the RSC tree: the data is already there on first load, serialized in the DOM or in a JavaScript variable, at the cost of a higher TTFB.
Good enough for a first try, and a good first exposure to the relevant React Server / Client APIs, but what would that look like?

Note: actually, this technique may be a good fit for a specific variant of SSG, where the Server Components are rendered during the build process, and only static files are shipped to production.

Inlining Server Components Output into the HTML Shell #

First, we need to adapt our index.html HTML shell template, and define a slot to inject our React Flight data.

<body>
  <div id="root"></div>
  <script id="react-flight" type="react/flight">
    <!--FLIGHT-->
  </script>
</body>

Then, in our web server (here, written with Fastify), create a route handler that will render our React Server Components tree into a PipeableStream, which we pipe to our flightStream WritableStream, letting us accumulate the React Flight chunks into a string.
We then await finished(flightStream) to wait for all the chunks to be written, and finally inject the complete React Flight Response in our template.

const { readFileSync } = require("node:fs");
const stream = require("node:stream");
const { finished } = require("node:stream/promises");

const React = require("react");
const { renderToPipeableStream } = require("react-server-dom-webpack/server");

const { App } = require("../src/app/app");

const MANIFEST = readFileSync(
  path.resolve(__dirname, "../dist/react-client-manifest.json"),
  "utf8"
);
const MODULE_MAP = JSON.parse(MANIFEST);

const HTML_SHELL = readFileSync(
  path.resolve(__dirname, "../dist/index.html"),
  "utf8"
);

function renderReactTree(writable, component, props) {
  const { pipe } = renderToPipeableStream(
    React.createElement(component, props),
    MODULE_MAP
  );
  pipe(writable);
}

const fastify = Fastify();

fastify.get(async function routeHandler(request, reply) {
  let flightResponse = "";
  const flightStream = new stream.Writable({
    write: (chunk, encoding, next) => {
      flightResponse += chunk;
      next();
    },
  });
  renderReactTree(flightStream, App, {});

  await finished(flightStream);

  reply.header("Content-Type", "text/html");
  return HTML_SHELL.replace("<!--FLIGHT-->", JSON.stringify(flightResponse));
});

Now we're able to render React Server Components on the server, and inline the output data inside our HTML template.
Nice, but how do we then pick that up to be rendered on the client?

Rendering Server Components Output on the Client #

We first need to retrieve the inlined React Flight data from the DOM <script> tag, transform it into a ReadableStream (here using the Response().body trick for convenience), before we feed it to React Flight Client API createFromReadableStream & obtain a Promise-like object, which we can finally pass to the use() hook from our <Root /> application root React Component.

import { createElement, use } from "react";

import { createRoot } from "react-dom/client";
import { createFromReadableStream } from "react-server-dom-webpack/client";

function Root({ flightTreePromise }) {
  return use(flightTreePromise);
}

const flightEl = document.getElementById("react-flight");
const flightResponseText = JSON.parse(flightEl.textContent);

const flightTreePromise = createFromReadableStream(
  new Response(flightResponseText).body
);

const root = createRoot(document.getElementById("root"));

root.render(<Root flightTreePromise={flightTreePromise} />);

Data-Fetching in Server Components #

Adding Data-Fetching with `async` / `await` #

export async function App() {
  const items = await new Promise((resolve) =>
    setTimeout(() => resolve([]), 1000)
  );

  return (
    <Layout header={<Header />}>
      <List items={items} />
    </Layout>
  );
}

The rendering of the <App /> component becomes truly asynchronous, it is streamed in multiple chunks, starting with a first chunk, immediately before the await, then followed by the remaining second chunk after the Promise resolves, including the rendering output of the <Layout>, <Header /> & <List> components.

Data-Fetching in child components: waterfall? #

Let's now make the <List /> component async with a similar data-fetching constraint.

export async function List({ items }) {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  ...
}

The rendering of the <List /> component only starts after the <App />'s awaited Promise resolves, and the awaited Promise of <List /> in turn, blocks the rendering of further child components. The second chunk now only includes the output of the <App /> component, the output of the <List /> component is only emitted in a third chunk, after it's awaited Promise has resolved.

In other words,the Server Components tree is rendered & streamed asynchronously, naive use of async/await for data-fetching in server components induces a waterfall.

Are there other options available to us?

Moving the `async`/`await` down #

Let's simplify our <App /> for clarity, and adapt it to trigger data-fetching at render-time as previously, but we remove the async / await from it, and move the async/await down to the <List /> component:

export function App() {
  const itemsPromise = new Promise((resolve) =>
    setTimeout(() => resolve([]), 1000)
  );

  return <List itemsPromise={itemsPromise} />;
}

export async function List({ itemsPromise }) {
  const items = await itemsPromise;
  ...
}

A fourth chunk makes its appearance, containing the output of the <List /> component, after the await of the itemsPromise Promise has resolved.
Although this is progress, in that instead of passing a resolved Promise value prop to children, we're passing a Promise props directly, and the component actually making use of the Promise is the one awaiting it, without blocking the rendering of (or data-fetching inside) other children of the <App /> component: still a waterfall, still idiomatic JavaScript & Promise handling, but slightly better

We mentioned earlier that React Server Components integrate with Suspense, but how do we leverage it?

Suspense-enabled streaming #

With async/await #

Using async/await in Server Components is compatible with <Suspense>, so all we need to do is to wrap it around our <List /> component, and give it a fallback React Node, to be used while the Promise is pending.

export function App() {
  console.log("rendering <App /> component");
  const itemsPromise = new Promise((resolve) =>
    setTimeout(() => resolve(["Suspense-enabled streaming"]), 1000)
  );

  return (
    <Suspense fallback="Loading ...">
      <List itemsPromise={itemsPromise} />
    </Suspense>
  );
}

export async function List({ itemsPromise }) {
  console.log("before the await");
  const items = await itemsPromise;
  console.log("after the await");

  return (
    <ul className="List">
      {items.map((item) => (
        <li>{item}</li>
      ))}
    </ul>
  );
}

We can see in our server logs the following sequence:

rendering <App /> component
before the await

Then as you'd expect, one second later:

after the await

Which translates to the following React Flight chunks (RSC Payload):

1:"$Sreact.suspense"
0:["$","$1",null,{"fallback":"Loading ...","children":"$L2"}]

Then one second later:

2:["$","ul",null,{"className":"List","children":[["$","li",null,{"children":"Suspense-enabled streaming"}]]}]

The usage of async / await in a Server Component wrapped in Suspense causes said component's render to be postponed.
This is the idiomatic, recommended pattern for data-fetching in Server Components with Suspense.

In the browser - with either a specific SSR implementation with RSC streaming support, or a client app able to render streamed React Flight chunks - this would result in the following sequence displayed on the screen:

render the Loading... suspense fallback
wait 1second for the next chunk to come in
replace the Loading... suspense fallback with the following HTML / DOM:

<ul>
  <li>Suspense-enabled streaming</li>
</ul>

But what about use() experimental hook?
Didn't we say that use() allowed us to handle Promises in components, in conjunction with Suspense?

use() vs async/await #

The use() experimental hook indeed lets us consume Promises inside React Components.
If we take the code of our <List /> server component from the previous example, remove the async / await and replace it with use(itemsPromise) instead, our server components behave almost the same:

import { use } from 'react';

export function List({ itemsPromise }) {
  console.log("before the use()");
  const items = use(itemsPromise);
  console.log("after the use()");
  ...
}

The practical difference between use() and async/await in server components is that in the use() case, the use hook tracks the state of the provided Promise, by checking its Thenable.status.

if the Thenable.status is pending or rejected, it suspends (interrupts) the rendering of the component
if the Thenable.status is fulfilled, it returns the resolved value, and resumes rendering the component

The rendering of a component suspended with use() - contrarily to a postponed server component with async/await - will be resumed once the Thenable (Promise) ultimately resolves.
Effectively, the render of the component is replayed.
The details of the use() hook are complex, but we can observe the general behavior in our server logs:

rendering <App /> component
before the use()

Then one second later:

before the use()
after the use()

Notice how the before the use() message is logged twice.
The use() hook has caused our <List /> component to suspend, and once itemsPromise has resolved, its rendering is resumed by being replayed.

This translates to both an identical RSC Payload, and an identical output displayed in the browser, as in the previous example with async/await.

Passing the Server's pending Promise to the Client #

Honestly, this is all already pretty good.
But we can go even further than that: what if we could start fetching data on the server and directly consume the Promise on the client?
Let's consider the perfect use() case: that our <List /> component, is in fact a Client Component.

First, we need to add the 'use client' directive to our list.jsx module.

"use client";

// List component ...

As previously, we still want to consume the itemsPromise in the <List /> component.
But our <List /> component is now a Client Component, and as such, cannot be async, thus cannot use async/await.

The solution, you've guessed it, is with the use() hook.

`use()` the force, Luke #

"use client";

export function List({ itemsPromise }) {
  // `itemsPromise` is passed from a Server Component to a Client Component!
  const items = use(itemsPromise);
  ...
}

This results in the following RSC Flight chunks:

1:"$Sreact.suspense"
2:I["./src/app/list.jsx",["client3","client3.chunk.js"],"List"]
0:["$","$1",null,{"fallback":"Loading ...","children":["$","$L2",null,{"itemsPromise":"$@3"}]}]

And then one-second later, the contents of our itemsPromise:

3:["Suspense-enabled streaming"]

This is where things get really interesting - to be continued...

Waterfall waterfall waterfall #

We succeeded in performing React Server Components Suspense-enabled data-fetching & streamed rendering!
This is great! It's better than our previous solutions of awaiting Promises in any component, because our solution now correctly leverages <Suspense />!
But what about the waterfall? We only have a single (<App />) component that is doing data-fetching, and only a single component (<List />) consuming an async data source here...

If we add another async component with await (or use()) anywhere in the <List /> subtree, we will still be introducing an async waterfall.
Fetching data in components is inherently subject to waterfall, even when leveraging best practices with React Server Components, Suspense, async rendering, simply because the data fetching within a component, cannot start until this component has started to render, which is potentially blocked by the data-fetching of the parent component.

And that's fine actually™: even though waterfall results in slightly suboptimal UX, it doesn't mean it's bad UX either!
Most of the time, waterfalls - even without all the combined benefits of RSC & Suspense - can yield a perfectly satisfactory experience.
And when it doesn't, there are multiple ways to mitigate the waterfall itself or its impact: composition, moving data-fetching up or down the tree, backend for frontend, optimizing, adapting or re-designing the API, etc...

Alternatively, if one really wants to avoid the waterfall problem inherent to fetching data from components, then one must move the data fetching outside of the component.
This problem has been known for a long time now and frameworks, libraries & patterns exist to solve it, such as Remix / React Router Loaders or Relay / GraphQL, in which case, the data requirements are defined, not in the component, but generally in the module, alongside the component.

Further alternatively, components could be responsible for defining their data requirements "what to fetch", and delegating the actual data-fetching to another system.

Finally, there might be compilers which will attempt to optimize data-fetching in RSC, and eliminate or mitigate some waterfalls automatically.

Routing with Server Components? #

Our original React Notes App uses a custom Router, leveraging the React Context API & the a-route library.
As such, it is client-side only & does not work with React Server Components.
In fact, the majority of the React Routing tooling out there, won't work with React Server Components.

I had to make a few tweaks to the original router implementation in our RSC Notes App, here is the (suboptimal) outcome:

the (not great) initial implementation of the router was completely broken when I migrated to RSC, partly due to now unnecessary use of useEffect & render-functions.
routes and their matching component are defined in a routes.js module, which is imported both on the server & on the client
routes are matched both on the server for the initial load, and on the client for client-side navigation
routes can be matched similarly by chance, because a-route's route matching is similar to Express' with path-to-regexp, and Fastify uses a similar route format
after matching the route on the server, we deduce a location object which is similar to the few properties of window.location we use on the client
the routing props are passed when rendering the App server component, so server components can use that
the client-side router is autonomous, doesn't rely on values computed on the client
all routes are Client Components, only the root component including the layout shared by all routes, as well as some of its children, are server components in our implementation

But all in all, our solution kinda works and the app is functional, objective completed!

A couple more things I would like to mention here in regard to routing with Server Components is that:

Route components should probably either be all client components or server components, supporting both risks being formidably complex & confusing for the developer.
The route matching logic should live outside of React, so it can be used on the server as well.
Moving route paths & components definition outside of React, ie, in a boring module which can be imported, makes things easier.

I invite you to take a look at our RSC React Notes App routing implementation & experiment for yourself.
Maybe try to plug-in some of the most popular React routing libraries out there, see what happens.
Maybe I'll try some things myself and update this section at a later time.

Form handling with Server Components #

I didn't have the opportunity to experiment a lot with form handling in server components for two reasons:

Server Actions for example are not supported by our setup
our forms (note creation, edition, deletion) are all client-side:
- due to limitations of our router implementation
- to prevent abuse (since the demo is hosted & available to the public)

But I took the opportunity to play with React Client Actions.

React Client Actions #

React Client Actions (like React Server Actions) are async functions that can be passed to the <form action={...}> & <button formAction={...}>, <input type="submit" formAction={...} /> React host / native elements props.
In the case of Client Actions only, they allow developers to write form handling logic, slightly more efficiently, and handle form submission render updates to be handled asynchronously by React.

Until now, these props were expected to follow the
<form> Form HTML Element's action <input>, <button> Form HTML Element's formaction attributes standard behavior, but not anymore: with Server / Client actions: they accept async functions.

Server / Client Actions encourage Locality of Behaviour.

However, in our original React Notes App, we use the same <Form /> component in the Create & Edit route components.
Therefore the note creation & edition logic is actually split between two components.
So our Form.jsx component looks a little bit like this:

import { useState } from "react";

export function Form({
  formId,
  handleAction,

  children: renderAdjacent = null,

  item = null,
}) {
  const { id = null, title = "", content = "" } = item ?? {};
  const [submitting, setSubmitting] = useState(false);

  return (
    <>
      <form
        id={formId}
        role="form"
        className="Form"
        action={async function handleFormAction(formData) {
          setSubmitting(true);
          await handleAction(Object.fromEntries(formData));
          setSubmitting(false);
        }}
      >
        ...
      </form>
      <div className="Form-actions">
        {typeof renderAdjacent === "function" && renderAdjacent({ submitting })}
      </div>
    </>
  );
}

And our Create.jsx component, like this:

"use client";
import { useRouter } from "./router";
import { useItemMutation } from "./items";

import { Form } from "./form";
import { Button } from "./button";

import { generateId } from "../utils/id";

export function Create() {
  const router = useRouter();
  const { addItem } = useItemMutation();

  return (
    <div className="Create">
      <Form
        formId="create-form"
        handleAction={async function handleCreateAction(values) {
          const item = {
            ...values,
            id: generateId(),
          };

          await new Promise((resolve) => setTimeout(resolve, 500));
          addItem(item);
          router.navigate(`/view/${item.id}`);
        }}
      >
        {({ submitting }) => (
          <Button type="submit" form="create-form" disabled={submitting}>
            Create
          </Button>
        )}
      </Form>
    </div>
  );
}

As you may notice, our implementation relies on a submitting React state variable.
I wanted to use the new useFormStatus experimental hook in the Create component to enable the disabled prop on our <Button /> component when the form is submitting.

Unfortunately, this is not possible because useFormStatus only works for components rendered within a <form> element, and our submit button actually lives outside of the <form> element.
This can be easily fixed by creating a <SubmitButton /> component and rendering it as part of the <form> subtree.

However, rendering form submit buttons outside of a <form> element, leveraging the form property with a form id is very common nowadays.
I wish we could have used the useFormStatus hook outside of a <form> element, possibly supplying it a formId.

Should you be writing your own RSC framework? #

There is no doubt, the RSC model is very powerful.

As we've seen together, implementing it from scratch is not going to be an easy feat, due to the inherent complexity of React Server Components of course, and in my opinion, due to the lack of shared building blocks provided by the React Team, and the fact that the ones provided are largely under-documented today.
Which of course leads to frameworks (Next.js) owning a very large part of the model - and necessarily leading to slightly different implementations, probably incompatible with one another.

Therefore I would not recommend product or platform teams to implement their own RSC framework in the current state of things.
However, I do recommend individuals, Open Source contributors to experiment with this technology and challenge the status-quo.
I know some exceptionally smart & capable folks (much more than me) in the community are actively reverse-engineering Next.js & driving innovation, I just wish there more.

Should you be migrating your Full-Stack React Framework to RSC? #

This is a trick question.

On one hand, I absolutely want to recommend teams with an existing in-house Full-Stack React Framework to progressively migrate to RSC.
On the other hand, this is going to be a tremendous amount of research, reverse-engineering, migration & documentation work that will span over months if not years.

But at the same time, chances are, a move to RSC is going to allow you to modernize your architecture, leverage ~~experimental~~ modern React features, improve the architecture of your applications, write more efficient code more efficiently while also being a formidable catalyst for removing legacy debt.

Conceptually, RSC features allow to simplify or completely remove a lot of things that your framework was doing:

code-splitting becomes infinitely easier if not automatic with 'use client' whereas it was probably manual previously (if it was even in place)
server-side data-fetching in components is baked-in whereas it was previously entirely custom & full of caveats (ie: confined to route components, relying on a feature of a specific router library)
SSR streaming although currently incomplete (to my knowledge) as provided by the React Team today, is incredibly more efficient with React Flight than anything we've seen or done before
progressive enhancement with Server Actions, despite their downsides, is likely to be a better solution than whatever we used to do to handle React form submissions without JavaScript
expensive components rendering can in some cases be moved to the server
bundle size reduction with Server Components & Server Actions, huge JavaScript libraries can be moved to the server while only their final output is sent to the client
and more!

In any case, I would honestly wait a bit longer.
There are plenty of debates about RSC & other modern / experimental React features being stable or production-ready (and more) going on these days.
It's pretty obvious from the content of this blog post, despite my potential mistakes and it not being exhaustive, that this debate is legitimate.
I also think there needs to be more divesity & a wider adoption in the ecosystem.

Going further with RSC #

server-only & client-only packages #

The server-only & client-only packages (or equivalent) are strongly recommended when working with RSC / Server Actions, for security reasons first, and potentially bundle size or load/runtime performance second.
These packages help preventing that code, supposed to run exclusively on the server, to be inadvertently imported from client code, or vice versa.

It's important to understand that these are nothing more than packages with an explicit name, placed at a convenient place - the top of a file with other imports - which immediately throw an error with a descriptive error message, at runtime.

'server-only' cannot be imported from a Client Component module. It should only be used from a Server Component.

// server-only index.js
throw new Error(
  "This module cannot be imported from a Client Component module. " +
    "It should only be used from a Server Component."
);

// server-only package.json
"exports": {
  ".": {
    "react-server": "./empty.js",
    "default": "./index.js"
  }

As we can see, these packages leverage package.json conditional exports with the react-server custom condition - supported by Node.js (node --conditions react-server server.js) & bundlers (such as Webpack - with resolve.conditionNames) to inject either the throwing module, or an empty "no-op" module, depending on the consumer environment.

Note: a potential alternative, would have been to use the default: null target, which would have rendered the package impossible to import from an environment that does not satisfy the react-server condition, causing an error at build time, or at runtime if there's no build step, and even possibly surfacing right in the developer's code editor thanks to static analysis with TypeScript for example.
Although this alternative seems to be superior in every aspect to me, I haven't tested it so it's only theoritical.
I am not aware of whether or not this alternative has been considered by the React Team, or if it did, why it wasn't chosen.

If custom resolution conditions such as react-server don't really work for you, or if you want to go further, rather than just throwing an error at runtime - which can be overlooked in some scenarios, and, from a productivity standpoint, potentially occurs too late in the developer's workflow, incurring an avoidable loss of productivity - it's a good idea to, like Next.js does, error at build time at the bundler level, which is guaranteed to be more reliable (and still relying on the error being thrown at runtime as a safeguard), while also happenning much earlier in the process.
This however assumes bundling for the target environment & requires additional processing & configuration, which of course, come at a cost, however relatively small.

React taint APIs #

We've mentioned earlier that Server Components can pass props to Client Components (React docs).
Simply put, React Taint APIs allow you to “taint” or mark JavaScript values & objects that must not be passed from the server to client, either by being passed from a Server Component to a Client component - in other words: which may not be serialized by React Server serialization APIs.
I haven't had the occasion to personally try them out & research them further, but these APIs are without a doubt primordial to handle secrets with React Server features, and should be used in conjunction with previously mentioned server-only.

Official React docs:

Facebook/react package source code for the APIs mentioned above, on GitHub:

React Taint APIs

React Server & Client Actions #

Announcements #

React Server & Client Actions were announced on October 23rd 2023 to be available in React Canary releases, starting from October 5, 2023 (18.3.0-canary-546178f91-20231005).

Three days later, Next.js announced on October 26th 2023 in Next.js 14 “Server Actions (stable)”.

Ecosystem #

This means the React Team considers these features frameworks, libraries (and the rest of the relevant ecosystem) can now adopt these features.
At the time of writing and to my knowledge, these features are for the most part, only adopted by Next.js.
The Remix React framework, has had a custom, somewhat similar feature to Server Actions for some time with Remix Actions.

Philosophy #

React Server & Client actions are inscribed in a dynamic from the React Team to provide efficient APIs for form handling, mutations, data fetching & reducing client-side JavaScript bundle size, promoting a Progressive Enhancement design philosophy with SSR.

Thanks for reading! #

If you enjoyed this blog post, please feel free to share it and let me know on Twitter or Mastodon, don't hesitate to take a look at my about page as well.

Further content may be added in the future, clarifications & corrections as well if needed.
Follow-up blog posts covering experimental or modern React features should be added in the future.
Clarifications & corrections may be added as well if needed - please let me know, feedback & discussions are welcome!

TypeScript Legacy Experimental Decorators with Type Metadata in 2023

2023-10-14T00:00:00+00:00

TL;DR #

“Just use Vite” (+ SWC)

npm i --save-dev vite vite-plugin-swc-transform

import { defineConfig } from "vite";
import swc from "vite-plugin-swc-transform";

export default defineConfig({
  plugins: [
    swc({
      swcOptions: {
        jsc: {
          target: "ES2021",
          transform: {
            legacyDecorator: true,
            decoratorMetadata: true,
          },
          // externalHelpers: true,
        },
      },
    }),
  ],
});

“kthxbye”

Problem #

I need to compile TypeScript code leveraging TypeScript Legacy / Experimental Decorators with Type Metadata.
I also need this compilation to be reasonably fast.
And then, I really want this compilation to be identical, as much as possible, between automated (unit & integration) & production.

The Old Ways #

So far, my current setup involves:

jest framework for automated tests
babel-jest, the default Jest transformer, with a custom Babel preset including @babel/plugin-proposal-decorators & babel-plugin-transform-typescript-metadata
tsc, the TypeScript compiler to transpile the code for production for an ES2021 browser target, using --experimentalDecorators & --emitDecoratorMetadata flags

Bonus: leveraging the importHelpers tsconfig.json flag & tslib to optimize TypeScript compilation output with tsc & final JavaScript bundle size by reducing duplication of TypeScript runtime helpers - which in the case of legacy decorators & type metadata, quickly add up to hundreds of kilobytes of pure, unnecessary bloat.

The above works reasonably well, both in the context of automated testing (tens of developers) & production (hundreds of thousands of end-users).

But as you can see, there are two problems with this current setup:

The compilation is slow enough to:
- be frustrating in many developer scenarios
- incur significant infrastructure costs for building packages & applications at this scale
Slightly different transforms are used by different compilers in automated testing & production build:
- potentially leading to subtle bugs
- overcomplicating the overall setup

Why not compile for production using Babel? #

Yes. Using Babel instead of tsc for the production code compilation would improve the current situation in regard to the two problems mentioned above:

Babel is slightly faster than tsc
Babel & popular Babel plugins are often considered the source of truth when it comes to compile transforms correctness

But, Babel's rich plugin ecosystem & fine-grained transforms being its most important strengths, they're also its biggest weakness in that, they make, by nature, Babel more difficult to correctly configure & maintain over time.

That is the main reason why I couldn't convince my peers to use Babel over tsc for production code compilation of a certain kind of library packages in early 2022.
As a result, production code compilation with Babel did not make the cut to ts-package-base, the first iteration of my TypeScript / Decorators / Metadata / React library package setup design with dual CJS/ESM compilation.

Note: To this day, Babel remains my personal favourite JavaScript compiler.

Times have changed, expectations too #

As sad as it may be, Babel & tsc are not longer the JavaScript compilers of choice in modern projects.

The lines between a runtime, compiler, bundler & minimizer have been blurred by a new generation of tools and their combination, such as esbuild, SWC, tsup, Vite or even Bun and more..

These next-gen tools are all powerered or super-charged, in one way or another, by the arcane power of compiled languages such as Go, Rust or Zig, offering build performance unparalleled in the JavaScript world.

Although they can, occasionally & to some degree, lack the maturity, correctness, ecosystem or functionality offered by their classic counterparts such as Webpack & Babel, there's also been a perception shift in the JavaScript community.
Whereas a few years ago, Webpack & Babel were the tools we loved to hate, next-gen tooling is hype, thanks to, in some cases, funding, marketing, dedicated conferences, polished communication & integration in popular / hyped web frameworks.

In conclusion: the classic tooling simply isn't good enough anymore, not necessarily in absolute, objective terms such as maturity, correctness, ecosystem or functionality, but, according to my own experience, in raw performance & developers perception.

Note: The next-gen tools I'm mentioning here generally also have a remarkable focus on Developer Experience & sensible feature priorization according to popular use cases, which of course also contributes to their success.
There is also a multitude of other factors explaining the fall or rise in popularity of these tools, whether they be considered as classic or next-gen.

Anyway #

Let's get back to our initial problem statement, after a quick re-introduction to TypeScript Decorators & Metadata.

TypeScript Legacy / Experimental / Stage 2 Decorators (experimentalDecorators) #

TypeScript Legacy / Experimental / Stage 2 Decorators are a natural evolution of TypeScript Classes.
Composed & applied to classes, class accessors, method & method parameters, they are commonly used for performing validation, transformation, augmentation, proxying or dependency injection, for which they're notoriously used with Angular, Nest & TypeORM.

Since their introduction in TypeScript, Legacy / Experimental / Stage 2 Decorators support can be enabled through the --experimentalDecorators flag (experimentalDecorators in tsconfig.json).

Note: see also:

Decorators Type Metadata (emitDecoratorMetadata / Reflect.metadata / reflect-metadata) #

The Metadata API Proposal specifies how to inject metadata to classes & objects, primarily through decorators ("annotations"), as well as reading this metadata through reflection.

TypeScript's Decorators Type Metadata in particular, allows to inject design-time types:

design:type
design:paramtypes
design:returntype

It relies on the experimental metadata API, also know as Reflect.metadata & for which the reflect-metadata npm package provides a shim.

In TypeScript, experimental decorators type metadata support & transforms are available through the --emitDecoratorMetadata flag, (emitDecoratorMetadata in tsconfig.json).

Note: see also detailed ECMAScript Metadata Proposal.

TypeScript, putting the Java back in JavaScript

Vite? #

Yes.

Vitest? #

Also yes.

TypeScript Legacy Experimental Decorators with Type Metadata with Vite? #

No.
Or at least, not by default.
Vite uses the esbuild transformer / compiler / bundler / minimizer by default, but unfortunately esbuild does not support emitting decorators metadata.
Therefore, we need to use a different JavaScript transformer / compiler.

The best compiler for TypeScript Legacy Experimental Decorators with Type Metadata? #

We've previously mentioned that TypeScript / tsc & Babel classic compilers support transforming both features, either behind flags, or through plugins, both of which are used in my current production setup.

Surely there must be a next-gen compiler which supports those features as well, right? right?

According to my research, SWC is the only next-gen compiler supporting legacyDecorator & emitDecoratorMetadata at the moment.
Furthermore, SWC also has a externalHelpers option, similar to TypeScript's importHelpers / tslib, it allows re-using injected helper code by relying on helpers code from a swc/helpers package instead of inlining helpers, which is invaluable to limit bundle size impact.
But wait... it gets better!
Indeed, @swc/helpers actually leverage's tslib's own helpers for decorator & metadata helpers!

And that's absolutely splendid for us!
Since our production code is currently compiled with typescript / tsc + tslib, using SWC to compile our TypeScript Decorators & Metadata code is guaranteed to produce identical output!

However, it's important to note that the rest of the transforms incurred by TypeScript may be implemented differently by SWC and can still be subject to subtle bugs.

Vite + SWC? #

Multiple plugins exist for handing over transform responsability to SWC in Vite, to name a few:

They all seemed to work, as far as I could tell from my limited testing.
But diving at the implementation & documentation for each of them, it appeared they all covered much larger use cases (React Refresh, Rollup, minification ...) than my own, sometimes with significant overhead, complexity or opinionated API.

vite-plugin-swc-transform #

I'm probably already paying an overhead cost by using Vite instead of running SWC directly for reasons explained above and then some, and I wanted to use a SWC plugin for Vite with the most minimal & transparent API surface.

Therefore, I decided to implement my own simple Vite plugin for transforming TypeScript Decorators + Metadata source files with SWC.

See vite-plugin-swc-transform on GitHub.

Please note this plugin is not necessarily meant as a replacement of alternative plugins.
It is rather intended as a way to address my own use cases efficiently.

However, please feel free to open an issue on GitHub if you have ideas on how it could be improved, or additional use cases you'd like it to support.

tsc vs Vite + SWC #

For comparing tsc to Vite + SWC, we'll be focusing on a single case study matching my main current use case:
Building a typical library package for production as ES2021 target ESM, composed of 124 TypeScript modules, a fair amount of which leverage TypeScript Legacy Decorators & Metadata, intended to run primarily in a browser after being bundled in a web project.

Speed: build performance benchmark #

The benchmark is running on an ~old Intel Macbook Pro.
Both builds output ESM for an ES2021 target.
The tsconfig.json file used for the tsc build is reasonably optimized for build performance with minimal type-checking.
Vite is configured to not attempt bundling nor minifying, and preserve the source directory structure in the output directory.

Benchmark 1: pnpm run build:esm:tsc
  Time (mean ± σ):      3.733 s ±  0.028 s    [User: 6.339 s, System: 0.429 s]
  Range (min … max):    3.696 s …  3.799 s    10 runs

Benchmark 2: pnpm run build:esm:vite-swc
  Time (mean ± σ):      1.347 s ±  0.031 s    [User: 1.650 s, System: 0.309 s]
  Range (min … max):    1.324 s …  1.432 s    10 runs

Summary
  pnpm run build:esm:vite-swc ran 2.77 ± 0.07 times faster than pnpm run build:esm:tsc

Vite + SWC is ~2.77 times faster than tsc in this configuration.

Correctness: compiled JavaScript output review #

When evaluating or switching JavaScript compilers, simply relying on an existing automated tests suite or manual testing is, in my experience, generally not enough.
It's important to also review the compiled outputs, look for differences & identify potential issues, opportunities for improvement.

$ wc -l esm-es2021-tsc-vs-vite-swc.pretty.patch
> 6826

SWC adds `.js` file extension to relative module imports #

The first & omnipresent difference in compilation output between tsc & Vite + SWC is SWC appending the .js file extension to relative module imports.

Our example package is advertised as ESM with type: 'module' in its package.json file & the input source code is composed of .ts files which use relative, extension-less imports.

This library package uses typescript@5.2, is configured with module: 'esnext' + moduleResolution: 'bundler' compiler options in tsconfig.json and is primarily intended to be consumed by a bundler, for building a web app running in the browser.

Extract from the actual diff between tsc & Vite + SWC outputs:

-import { isModuleImplementationDefinition } from '../dependency-injection/module.types';
+import { isModuleImplementationDefinition } from '../dependency-injection/module.types.js';

In our case, it's a safe change, and arguably a good one.

Indeed, bundlers & runtimes use different module resolution algorithms to be able to resolve actual modules from an import statement.
These algorithms can behave slightly differently from one to another, and by appending .js file extension to relative module imports, SWC clears the ambiguity of the possible files that should match a given compiled import.

This also results in a faster & more efficient module resolution process, because the algorithm doesn't have to check for files matching the import specifier, with multiple possible file extensions.

About TypeScript module resolution, module formats & compilation targets #

With tsc, module specifiers are not transformed.

If your project targets Node.js & compiles to ESM though, module: 'node16' (or 'nodenext) & moduleResolution: 'node16' (or nodenext) is the only correct tsconfig.json combination matching Node.js ES modules resolution algorithm.
In which case, you will be required by the TypeScript compiler to author relative module imports with their runtime specifier, in other words, with their runtime extension, ie .js - but that doesn't apply if you use moduleResolution: 'bundler' (which is our case here) or compile to CJS.

Learn more about TypeScript Module Theory & Module Resolution.

SWC & tsc set class properties differently: useDefineForClassFields #

Note: to be continued...

To be continued... #

This blog post only covers one, although crucial, aspect of my current quest, quest which I hope will result in a succesful & impactful migration.
Follow-up blog posts should be added in the future.
Clarifications & corrections may be added as well if needed.

Thanks for reading! #

If you enjoyed this blog post, please feel free to share it and let me know on Twitter or Mastodon, don't hesitate to take a look at my about page as well.

React memo is good actually

2023-10-06T00:00:00+00:00

Disclaimer #

This blog post expresses my personal views on a controversial, complex & ever evolving topic, based on my personal experience.
Your mileage may vary.

memo, useMemo, useCallback for performance (& logic correctness) #

React.memo, React.useMemo & React.useCallback, respectively a HOC & performance hooks, are official APIs provided by the React library ~since React@16 (2018), commonly yet hesitantly used in React applications.
They are notably used for improving application runtime & rendering performance, and regarding React.useMemo & React.useCallback hooks, also to ensure stability of non-primitive JavaScript values, when such values are used as effect hooks, ie React.useEffect dependencies.
In which case, they also contribute to application logic correctness.

Note: if you're not familiar with these APIs, I can't recommend enough to read the excellent React API Reference.

Great APIs, bad reputation, strong positions #

Since these they were introduced (and even before with React.PureComponent & React.Component.shouldComponentUpdate), React performance APIs have, in my opinion, suffered time and again from bad press: countless incorrect, oriented, biased, dishonest articles, medium posts, tweets, code review comments, opinions & rants, describing the APIs as “counter-productive, unnecessary, bad, evil” or even “dangerous”.
All with varying degrees of over-simplification, absolutes, subscribe buttons, links to YouTube channels, paid courses & workshops.

Thankfully, most of this content is old now and it's not brought up nearly as often as it used to a few years ago.
Unfortunately, they still rank very well on search engines and regularly make their way into colorful engagement-bait info-graphics on X dot com.

Of course, some actually great, nuanced & technically correct content exists covering in-depth React Rendering Behavior or alternative ways to improve React rendering performance - it's not necessarily the easiest to find, but not too difficult either.

But the problem is, bad press & demonization of APIs: it sticks.
Over the years (since what, 2017, 2018?) I have seen open source maintainers, tech leads, engineers, Senior, Staff+ alike, take very strong positions pushing back against the use of React performance APIs at work or in public, all in the name of “readability, anti-fragility, performance, simplicity, convenience, consistency, dogma”, and more.

All this with an outstanding immediate effect of leading to heated debates in code reviews, stalling pull requests, gatekeeping, drama, frustration, and too often as a result: a halt to efforts aiming to improve rendering performance for the users.

Most Common Misconceptions #

Let us review some of the most common misconceptions I've come across over the years, which, I believe, are both a consequence & a catalyst of React performance APIs bad reputation & related difficulties mentioned previously.

1. “React is so fast anyway, React.memo is unnecessary” #

INCORRECT

Although yes, React is fast enough in most cases, there's a reason these React performance APIs exist in the first place: they fill in a gap in React's model and a gap in the ability of teams to maintain a code base in par with state of the art practices over time.

Furthermore, the actual rendering performance of a client-side web application or SPA is dependent on many factors beyond the underlying view rendering library being “fast”.
These factors include the state of the code base, dependencies, use cases & functionalities, as well as external factors like the user's device or web browser.

Accordingly, rendering performance issues in React projects are extremely common, and can most of the time be mitigated or fully resolved with a combination of best practices, patterns, refactoring, re-architecture and tools, including React.memo.

2. “React.memo is counter-productive” #

Also known as “React.memo's props shallow-equality check's overhead is detrimental to performance”.

INCORRECT

React memoization in general & React.memo specifically can be counter-productive if it's not used correctly, ie: when used on a component that more often than not receives different props between renders, which will render memoization ineffective, while still incurring the cost of comparing previous memoized props with new props, (by default using a shallow-equal comparison).

In other cases where React.memo is used correctly, and some re-renders of the memoized components are legitimate because their props are legitimately different across renders, then yes, React.memo incurs an unnecessary overhead cost, mostly through its compare function - React's shallow equal comparison.

In any case, in real-life applications, React's shallow comparison's cost is arguably negligible & highly unlikely to be more expensive than a prevented re-render of any non-trivial component.

3. “React.memo doesn't work with React element / children props” #

INCORRECT

Well, not entirely incorrect, since React elements are commonly created using JSX, which is transformed to React.createElement(...) calls (or equivalent) , always returning new object, then yes, naive passing of React elements as props to a memoized component will render its memoization ineffective.

However, it won't be the case if you pass stable / constant React elements - ie defined outside of the parent function component's scope or memoized with React.useMemo.

The former can be done automatically where applicable using babel-plugin-transform-react-constant-element or equivalent compiler transforms - although when dealing with stable props to be passed to a React.memo'd component, it's best to be explicit than to rely on an implicit compiler transform.

Bonus: the re-render of a stable / constant React element will be skipped by React, regardless of it being memoized with React.memo or not.
This React behavior is also known as "same reference element optimization".

For instance, the following code renders the memoization of <MemoizedLayoutComponent> inneffective:

function App() {
  return (
    <MemoizedLayoutComponent>
      <SomeUIComponent />
    </MemoizedLayoutComponent>
  );
}

But the following - whether done manually as in this example, or automatically via babel-plugin-transform-react-constant-element - allows <MemoizedLayoutComponent>'s memoization to work as expected, and ensures our <SomeUIComponent /> child component to never be re-rendered (other than through an update of its own state).

const someUIElement = <SomeUIComponent />;
function App() {
  return <MemoizedComponent>{someUIElement}</MemoizedComponent>;
}

Note: The following variant, using React.useMemo on <SomeUIComponent /> when dealing with some dynamic props, although less recommendable, also works - both <SomeUIComponent> & <MemoizedComponent> will be re-rendered if dynamicProp changes (assuming a state update), but neither will ever be re-rendered otherwise:

function App() {
  const dynamicProp = useDynamicProp();
  const someUIElement = React.useMemo(
    <SomeUIComponent staticProp="static" dynamicProp={dynamicProp} />,
    [dynamicProp]
  );
  return <MemoizedComponent>{someUIElement}</MemoizedComponent>;
}

4. “React.memo is too fragile” #

DISAGREE

React.memo does have a weakness: in order to be effective, it requires the consumer of a memoized React component, to be aware that said React component has been wrapped by the React.memo HOC and thus, that its props are expected to be stable for component memoization to be effective.

Some argue that consumers of a React component shouldn't be aware of how said component is defined or exported, that it's an implementation detail.
I disagree.

I believe, like any function, any API you didn't write yourself, you should refer to the documentation, JSDoc definition, better yet, also refer to the source of truth: the source code, tests, and even in more cases that I'd like, compiler configuration & output!
What if the underlying component uses some of the provided props as React.useEffect() dependencies?

Regardless, this weakness can be addressed in multiple ways, such as adopting & documenting a naming convention within your team, indicating the memoized nature of the exported component, ie:

export const MemoizedList = React.memo(List);

Another naming convention could be to convey the necessity for specific non-primitive value props to be referentially stable as much as possible:

const { data = [] } = useData(queryKey);
const stableData = React.useMemo(data, []);
return <List stableData={stableData} />;

Note: this example relies on React.useMemo with an empty dependency array just for demonstration purposes.

Alternatively, you can to shift the responsability of wrapping the component to memoize with React.memo by doing it, not in the file where the component is exported, but it in the file where the component is used:

import React from "react";
import { List as RawList } from "./List";

const MemoizedList = React.memo(List);

function App() {
  const { data } = useStableData();
  return <MemoizedList data={data} />;
}

Additionally, React.memo() being a HOC, you could create your own wrapper around it, so it can be leveraged in a declarative way.

Something along those lines for example:

const { items } = useItems();
return <MyMemo component={List} items={items} />;

Note: I wouldn't recommend this, but it's possible.

Finally, alternatives to React.memo can be just as much fragile, in slightly different & subtle ways.
Arguably, React.memo & React.useMemo can be helpful if you want to render your code more robust.

Custom React Context Provider components for instance, are often used to provide both a getter & a setter to consumer components, encapsulating specific domain specific logic, and used in the application's entry-point component.
We can carefuly write our Custom React Context.Provider component in a way that doesn't make it necessary to use React.memo on the <Main /> component, assuming it renders an expensive subtree, and we can also avoid wrapping the provided value in React.useMemo().

const ThemeContext = React.createContext();

function ThemeContextProvider({ children }) {
  const [theme, setTheme] = useState("dark");
  const value = { theme, setTheme };
  return (
    <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
  );
}

export function App() {
  return (
    <ThemeContextProvider>
      <Main />
    </ThemeContextProvider>
  );
}

Note: I would probably do this too in most cases.

However, additional wrappers around or replacing an application's entry-point component over time are a reality, and any future changes in the code base introducing additional state updates in or above <App /> will render these careful efforts in avoiding React.memo & React.useMemo counter-productive.

Indeed, both <Main />, with its expensive subtree & <ThemeContextProvider> will re-render, a new value object created and then all React.useContext(ThemeContext) consumers will be re-rendered, even if the theme value hasn't changed.
Although we could split our <ThemeContextProvider> into a <ThemeGetterContextProvider> & <ThemeSetterContextProvider> to address this issue, we would lose the consolidation of our theme handling domain logic in a single component, introduce more friction in the code base & have to go through a refactor of all context consumers, potentially introducing risks.

Whereas we could have ensured the robustness of both our <App /> component, our ThemeContextProvider component & consumers from the start with React.memo & React.useMemo.
For the sake of demonstration:

const ThemeContext = React.createContext();

function ThemeContextProvider({ children }) {
  const [theme, setTheme] = useState("dark");
  const value = React.useMemo({ theme, setTheme }, [theme]);
  return (
    <ThemeContext.Provider value={value}>
      {children}
    </ThemeContext.Provider>
  );
}

const MemoizedMain = React.memo(Main);
export function App() {
  return (
    <ThemeContextProvider>
      <MemoizedMain>
    </ThemeContextProvider>
  )
}

Note: I would do this in some cases.

Or more explicitly:

const ThemeContext = React.createContext();

function ThemeContextProvider({ children }) {
  const [theme, setTheme] = useState("dark");

  // Although currently this component is rendered exactly once,
  // we memoize the context value preemptively to ensure it will never cause
  // unnecessary re-renders of its consumers, ie if this component becomes
  // subject to updates from its parent component, such as if it's moved closer to its consumers
  const value = React.useMemo({ theme, setTheme }, [theme]);
  return (
    <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
  );
}

export const MemoizedApp = React.memo(
  function App() {
    return (
      <ThemeContextProvider>
        <Main />
      </ThemeContextProvider>
    );
  },
  /**
   * The App component is our application entry-point.
   * and should only be rendered exactly once.
   **/
  (/* prevProps, newProps */) => {
    if (__DEV__) throw new Error("Unexpected re-render of <App /> entry-point");
    return true;
  }
);

Note:: I would only do this in specific cases.

5. “React.memo / React.useMemo / React.useCallback are signs of poor architecture” #

INCORRECT

Occasionally, maybe, it depends.
See 6. “There are better alternatives to React.memo / React.useMemo / React.useCallback”.
But my point is, even when the use of these APIs make possible improvements apparent - that may or may not allow not to use these APIs in the first place, the use of React Performance APIs in itself, is perfectly valid, at least pending the refactoring of the relevant code, which may or may not happen in the future, depending on a multitude of factors: complexity, resources, product pressure, etc.

6. “There are better alternatives to React.memo / React.useMemo / React.useCallback” #

SOMETIMES

Known best practices, patterns such as keeping component state as local as possible & lifting content up, tools such as state containers, etc. can often have an outstanding effect on rendering performance and render some React.memo uses unnecessary.

Effects with React.useEffect can sometimes be written in a way that doesn't rely on non-primitive value dependencies, thus removing the need for React.useMemo or React.useCallback.

But in a lot of real world situations, these aren't enough, nor even the best choice depending on the project's context: for example, more often than it seems, using these APIs and opting into “inferior” patterns is a better trade-off than the re-architecture of an application, rewriting a lot existing of code.

7. “React.memo / React.useMemo / React.useCallback are detrimental to readability & maintainability” #

DISAGREE

If they're misused? Sure - and I'm all for enforcing either using them correctly or not using them at all.

But as soon as these APIs are used correctly, I find they actually improve one's understanding of the code upon reading, and practically convey or highlight important information.

When I see React.memo used in a code base that otherwise doesn't use it much, I don't read:

“This component is optimized.”

I read:

“The components subtree in which this component is rendered, is maybe in the critical path, probably subject to unnecessary & potentially expensive re-renders relative to the other components in the code base.”

When I see React.memo used in a lot of places, I read:

“It's our philosophy that every component should be as efficient as possible.”

Similarly, when I see React.[useCallback/memo], I read:

“It's important for this value to adhere to immutability principles because it's computationally heavy or because we need to keep a stable reference, according to the following dependencies.
It's likely to be used by effects or other performance APIs.”

8. “But <authority figure> said not to use these APIs! (or similar)” #

INCORRECT

First of all they probably didn't say or mean that litterally.
Or maybe they did, but regardless - and however appreciative we can be for their contributions, recommendations, etc:

they don't write the code: we do.
they're not the ones who pay the price of bugs & inaction: our users do, and ultimately, we do too.
it's up to us, not them.

9. “Premature optimization is the root of all evil” #

DISAGREE

What is a premature optimization?
When does an optimization cease to be premature?
What evil are we talking about here?

More seriously, this quote, albeit super catchy & effective, is always dropped outside of its original context, which ironically, relates a very strong pro-optimization position.

”The conventional wisdom shared by many of today's software engineers calls for ignoring efficiency in the small; but I believe this is simply an overreaction to the abuses they see being practiced by penny-wise-and-pound-foolish programmers.” > Donald Knuth

I find it's often used as a lazy, vague, catch-all way to undermine someone's efforts or dismiss potential improvements, without much more justification - which, I'm sure you'll agree, isn't very nice or respectful of said someone's work.
In any case, I find it subjective, and would rather discuss the impact, the trade-offs or questions left to be answered, regarding the idea being challenged, in a more specific way.

Moreover, looking back at the previous points, one could absolutely use this quote in a similarily disinguenous way to argue in favor of using these APIs over the potentially more complex, consequential, time consuming & risky alternatives, when any.

Note: This quote is also used in a more seasoned fashion, as an invitation to perform measurements, use profiling, to identify hot code paths in order to guide & validate performance improvement efforts, which in itself is perfectly recommendable.

React memo, useMemo & useCallback are good, actually #

React performance APIs have some weaknesses, yes, most of which inherent to their nature, filling in the gaps in React's rendering model & allowing teams to mitigate issues of their own making.
However, incorrect uses of React performance APIs, in my experience, are mostly due to minor mistakes and inconsequential.
On the other hand, strategic & proper use of these APIs can have an outstanding beneficial impact, on rendering performance of course, but also more than that: in expressing intent, surfacing key components, highlighting opportunities, enabling use cases that would otherwise require introducing a tremendous amount complexity or additional work, shipping now what would otherwise require days.
All of which, in my book, makes React performance APIs exceptionally good, actually.

Demo: Let's build a notes app highlighting the value React performance APIs #

To be continued...: the idea would be to build, from scratch & step by step, a simple (fake) notes app, and during the process, highlighting the value of React performance APIs versus other possible alternatives, when any.

I'm not trying to convince you #

I consider that the uphill battle ~~of memoization~~ for the just & pragmatic recognition of the React performance APIs has long been lost.
I'm primarily writing this blog post for myself, and to serve as an educational reference and clarification of my views in case of future, alas inevitable, push-back & debates regarding the use of these APIs.
I wish the React community generally wasn't so dogmatic, but regardless, for as long as I will even remotely be in contact with React code & React developers, I know I will continue to actively push for writing React code that's as efficient as reasonably possible, not just because I'm a performance enthusiast and it's fun, but because it matters.

To be continued... #

There's obviously much more to say on React Performance APIs and other gravitating topics.
Further content (including the upcoming demo) may be added in the future, clarifications & corrections as well if needed.

Prior art: parisweb.app (2018) #

Demo apps for the React/Redux performance workshop “Petits trucs pour rendre vos applications React plus performantes” performed with Julien Wajsberg at a meetup hosted by Gandi and then at Paris Web in 2018.
The materials produced at this occasion (slides, code, examples) are mostly outdated, yet still somewhat relevant resources to understand and improve performance of React apps, with or without Redux, in 2023.

Thanks for reading! #

If you enjoyed this blog post, please feel free to share it and let me know on Twitter or Mastodon, don't hesitate to take a look at my about page as well.

CSRF When You Least Expect It.

2022-12-21T00:00:00+00:00

Update 2022-12-21: I acknowledge this blog post isn’t as fun or interesting as I wanted it to be, it also contains a couple of minor errors.
I still believe it covers an interesting topic, I’ll find a way to do it better.
Thanks again to anyone who has read it and offered me their feedback.

Update 2022-12-22: Previously stated that cookies were set with SameSite=Lax by default in modern browsers, which is incorrect.
Updated with accurate browser compatibility info, links to the updated standard, MDN compatibility table, Firefox bug tracker.

CSRF #

Photo by Kaitlyn Jackson - Unsplash

Cross-Site Request Forgery (CSRF) - a type of attack where the user's browser is tricked into performing unwanted actions on a target website, on behalf of the user - are among the most common web application security risks.
As such, CSRF is usually well known among web developers, and most of today's websites are sufficiently protected against its most severe forms by implementing a set of best practices & defense mechanisms (OWASP) (ie: CSRF tokens, request origin checks, not using GET requests for state changing operations, ...).

By the way, feel free to take a look at my Cross-Origin Resource Sharing For The Web (Extension) presentation for a refresher on the topic.

SameSite Cookies ? #

SameSite Cookies allows you to declare if a cookie should be restricted to a first-party or same-site context. In other words, with either SameSite=Lax or SameSite=Strict, a cookie will not be forwarded in cross-origin subrequests. Declaring session cookies as same-site are the best defense-in-depth mitigation against CSRF.

SameSite=Lax by default ? #

The Standard (RFC 6265bis specification) recently changed so that SameSite=Lax should be the default behavior if the SameSite attribute is not specified in the Set-Cookie HTTP response header.
However, as of today (December 22nd 2022), this default behavior is either not yet implemented (Safari) or not yet activated by default (Firefox), for 22% of current browser coverage according to browserslist.

SameSite=Lax default behavior browser compatiblity: #

Chrome / Chrome Android: 80
Edge: 86
Opera: 39
Opera Android: 60
Samsung Internet: 13
WebView Android: 80
Firefox: 69 (pref network.cookie.sameSite.laxByDefault - bugzilla)
Firefox Android: no
Safari / Safari iOS: no

See SameSite Cookies Browser Compatibility on MDN.

SameSite=None #

However, there are still many websites out there which rely on SameSite=None as they:

don't specify the SameSite attribute for their cookies, their Firefox & Safari users thus getting the SameSite=None behavior
already existed before the introduction of SameSite cookies (from around 2016 to 2020 depending on the browser and stage of implementation), and thus already had prior controls in place against CSRF
still need to include cookies in cross-site requests, probably for some obscure tracking purposes
aren't necessarily sure what they're doing

But since these sites are using other anti-CSRF mechanisms & SameSite cookies are “defense in depth”, this should be fine, right? RIGHT?
Well, mostly, I mean, kinda ... it depends ... ok not really.

Introducing Timing Attacks #

A timing attack is a side-channel attack in which an attacker is able to gather information by measuring the time various operations take to run.
It is usually referred to in the context of cryptographic algorithms, or in the case of transient execution CPU vulnerabilities such as the famous Spectre & Meltdown.

Timing Attacks ... on the Web ? #

However, per Wikipedia, “timing attacks can be applied to any algorithm that has data-dependent timing variation” and, what more than today's websites that, gated behind authentication & user accounts, querying a myriad of unequally optimized microservices in order to display user-specific content, are subject to ”data-dependent timing variation” ?
It is fair to assume the server handling requests to pages for user dashboards or social media timelines for example, behave slightly differently whether or not the user is logged-in or not.
Indeed, in a lot of cases, those requests will take significantly longer to be answered compared to the login page that is served (or redirected to) in its place.

Note: this assumption may not be true for some websites, nowadays even personalized content can be heavily cached, and public content may not be faster to retrieve either.
However, as mentioned earlier, things are rarely equally optimized, which means that even though the main personalized content of a given websites may be very fast to retrieve, it may not be not the case for more niche content, located at another URL.

Ok that's cool and all, but what does it have to do with CSRF & SameSite Cookies?

CSRF Based Web Timing Attacks #

Given a website that use SameSite=None for their session cookies, and, even with some safeguards against most common & severe forms of CSRF, we can still perform attacks that fall into the CSRF category, in fact, in an actually much simpler way than with usual forged cross-site requests.
The twist resides in actually sending out two simple GET requests, with & without credentials:

one cross-origin request omitting credentials (cookies), which will yield a public version of the page
one cross-origin request including credentials (cookies), which will yield the private version of the page if the victim is logged-in

We can do this easily with JavaScript using the Fetch API:

fetch("https://target.example.com/", {
  credentials: "include", // "omit"
});

Note: for optimal results on a case by case basis, one may further tune the parameters of the requests & the behavior of the browser according to the Fetch Standard, by using the mode & redirect options.

Now these requests are made from a given origin, let's say https://evil.example.com, to another origin, say https://target.example.com.
Of course, in real life those would be totally different domains, but in any case, they're different origins, and, for this example to be correct, we're assuming that session cookies weren't set with the Domain directive.

Due to Same-Origin Policy (and the target origin presumably not allowing our evil origin with the Access-Control-Allow-Origin: https://evil.example.com response header), the responses from these requests are opaque and cannot be read, so we can't poke around in the response HTML for the actual content.
But we're fine with that, as mentioned earlier, we're interested in the timing of things, and that, we do have access to!
All we have to do is to measure the time it took between the firing of the request, and the subsequent settlement (rejection) of the Fetch promise.
Again, this is only possible because https://target.example.com is using SameSite=None session cookies.

const start = Date.now();
const total = await fetch("https://target.example.com/", {
  credentials: "include", // "omit"
})
  // swallow the likely NetworkError exception occuring from the CORS error.
  .catch(() => {})
  .then(() => {
    const end = Date.now();
    return end - start;
  });

With the following code, we are able to put together an attacker webpage, get an hypothetical victim to visit it, and begin poking around to find out if, for a given URL, fetches take significantly longer to respond with credentials (cookies) included, or not.
If they do, chances are you are able to detect whether or not the user is logged-in to this particular website.

However, in order to have more confidence in the results, we should update our exploit code to be aware of what constitutes "significantly longer", for instance, we could draw the line at a 40% tolerance.
We also might want our code to repeat the experiment a few times and ensure that the results are the same 80% of the time, so we'd be able to tell the results are consistent.

View Gist with complete example code of the malicious page

How could this be used ? #

Such Web Timing Attacks could be used by bad actors in order to further identify potential targets, for example as the ~first of a multi-stage attack, starting from a spam campaign linking to a malicious webpage controlled by the attacker and containing the exploit code, allowing them to identify whether or not victims are users of specific sites or services, before engaging in a more targeted phishing campaign.
Depending on the website or service being targeted and after careful analysis by the attackers, one may even be able to gather more precise information about the victim than just their authentication status: potentially their customer profile (ie: a specific page of a given website may take a very long or telling time to load, when in the context of a large business).

How to prevent such web timing attacks ? #

Do not use SameSite=None, use either SameSite=Strict or SameSite=Lax: this way, cookies will not be forwarded in cross-origin subrequests.
Use a modern, up-to-date web browser, in fact, use Firefox.

Bad Performance is Bad Security #

One slightly disingenuous way of looking at this is to blame the feasability of this attack on the lack of performance focus: if everything is as fast as it can be, then a third party cannot interpolate private information based on response times.
Alternatively, one other way to look at this is to aim for making all requests roughly respond in the same time, by artificially slowing them down, but that would be silly, please don't do that.

Don't try this at home #

Or rather, please do try this at home, but don't use this for nefarious purposes, I wrote this article for fun and profit and somewhat educational purposes.

If you enjoyed this article, please feel free to share it and let me know on Twitter or Mastodon, don't hesitate to take a look at my about page as well.
Did I mention I'm looking for a job?

Cross-Origin Resource Sharing For The Web (Extension).

2021-03-16T00:00:00+00:00

As I'm getting close to my fifth month at Dashlane, I have given my second presentations to engineers within the Web Product Team.

The presentation aims to be a high-level introduction to Cross-Origin Resource Sharing.
It covers the key concepts needed to approach CORS:

Origin
Same-Origin Policy
Cross-Site Request Forgery (CSRF)
OPTIONS preflight requests

It also tells the tale of a CORS twist in the context of a Chrome Web Extension.
Finally, the presentation mentions the quickly evolving web security landscape in a post-spectre world.

This presentation is also kind of meant as a not so subtle invitation to:

double-checking your cross-origin setup.
being wary of relying on defaults implemented by browsers.
not blindly trusting the specifications.

Open “Cross-Origin Resource Sharing For The Web (Extension) (3.99MB pdf)”.

This presentation was given over video conference using screen sharing, in about 30 minutes excluding questions.

Forms handling with React: Giving Up Control.

2020-12-19T00:00:00+00:00

As announced on Twitter, I recently joined Dashlane, and gave my first presentation to engineers within the Web Product team.

The presentation aims to be a high-level introduction to forms handling with React.
It covers the key differences between a traditional form handling approach with JavaScript, and both the controlled input (or controlled component) and uncontrolled input approaches.
It also gives food for thought on how to consider going one way or the other for the implementation inside an existing React project for the Web.

This presentation is also kind of meant as a not so subtle invitation to:

further considering uncontrolled inputs in form implementations using React
keeping an open mind and remaining critical of “The React Philosophy (tm)” and thought leadering

If you're further interested, in particular by the performance implications of controlled inputs and React performance in general, I invite you to take a look at a previous presentation (in french), and other materials made at the occasion of Paris Web workshop in 2018: “Petits trucs pour rendre vos applications React plus performantes”.

Open “Forms handling with React: Giving Up Control (1.41MB pdf)”.

This presentation was given over video conference using screen sharing, in about 20 minutes excluding questions.

Read “Reflecting on our JavaScript footprint” on Gandi's blog.

2020-08-12T00:00:00+00:00

July 31th 2020 was my last day as Lead Front-End Engineer at Gandi.
As announced on Twitter, I have spent my last few hours there writing an article to be published on Gandi's blog: Reflecting on our JavaScript footprint.

After quickly describing the changes occuring on the Web, this article introduces the concept of JavaScript footprint by examining the architecture of two websites I have been working on at Gandi:

This article contains insights on how Gandi is organized, develops websites, the difficulties that are met, as well as some leads and solutions towards solving these.

There's a lot of interesting topics, contents that, for the sake of brievety, and in order to meet a very tight deadline, did not make it into the article that I intend to develop on this blog, so stay tuned. :)

Read Reflecting on our JavaScript footprint on Gandi's blog.

Limiting Asynchronous Operations Concurrency In JavaScript.

2020-08-07T00:00:00+00:00

Today's post is about a little trick I have learned about 2years ago, and that I have since used numerous times in short Node.js scripts I had to write.
It really isn't much, but I guess it may be helpful to others, and probably is an alright first JavaScript post on this blog.

Say one has a list of things, and for every of these things, one needs to perform an asynchronous operation that returns a Promise, and be notified when all operations have been performed. > How does one limit the number of asynchronous operations being performed conccurently? Without 3rd party dependencies and just a few lines of code?

Are you seeing the problem yet? Let's build some context:

We have a list of 99 things, say resource identifiers #

const ids = Array.from(Array(99), (_, i) => i + 1);
> [1, 2, 3, ... 99]

For each of these things, we need to perform an asynchronous operation #

First, let's define the function that will perform said asynchronous operation:

// We can pretend this performs an HTTP request
// an API call, or a database query.
function performAsyncOperation(id) {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log(`Performed operation for resource ${id}.`);
      resolve();
    }, 300);
  });
}

Now, we know that we need to call this function of every single thing out of our list of 99 things, every resource id we have in ids.
Our first approach, would be to naively use Array.prototype.map and Promise.all and call it a day. But let's have a closer look to this innocent line of code and its implications:

await Promise.all(ids.map(performAsyncOperation));
console.log("All operations performed, moving on to something else now.");

Note: we might arguably use Promise.allSettled in a real world scenario, but let's assume our asynchronous operations cannot fail.

Which we would give us the following complete script:

function performAsyncOperation(id) {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log(`Performed operation for resource ${id}.`);
      resolve();
    }, 300);
  });
}

async function run() {
  const start = Date.now();
  const ids = Array.from(Array(99), (_, i) => i + 1);

  await Promise.all(ids.map(performAsyncOperation));
  const end = Date.now();
  console.log(
    `All operations performed in ${
      end - start
    }ms, moving on to something else now.`
  );
}

run();

Now, let's run it:

$ node async-operations-promise-all.js

[tim@praxis ~]$ node limit-async.js
Performed operation for resource 1.
Performed operation for resource 2.
Performed operation for resource 3.
...
Performed operation for resource 97.
Performed operation for resource 98.
Performed operation for resource 99.
All operations performed in 338ms, moving on to something else now.

As we can see, ~all the asynchronous operations were performed concurrently, and sometimes, that's perfectly fine and exactly what we want.

Note: Promise.all only waits for all the Promises to be resolved. The actual asynchronous operation is triggered by the function call from Array.prototype.map, creating a new Promise on each call.

The problem of performing operations concurrently #

Now, let's assume that our performAsyncOperation really performs an HTTP request, an API Call, a database query, or really anything else that would either suffer or punish us for the load we push on to it. It might be a rate-limited API, or a fragile host.

Note: in the actual case of an HTTP request, or database query, the Web/Node.js/etc... API being used will already probably limit concurrency, of which value may or may not configurable, but let's assume that we cannot or do not want to change such settings.

In such cases, we simply cannot allow our script to perform all these operations concurrently, as it risks getting our API key revoked, our IP blocked, or the target host/database responding unreliably, etc... Thus we will be searching for a way to limit JavaScript concurrency to avoid such scenario.

Note: depending on the actual work performed by the asynchronous operation, performing many of these concurrently may also make the process running it consuming significant amount of CPU and/or memory resources on the machine it runs.

A solution: performing asynchronous operations sequentially #

The first solution that may come to mind, would be to perform each of these operations sequentially, on task at a time:

async function run() {
  const start = Date.now();
  const ids = Array.from(Array(99), (_, i) => i + 1);

  - await Promise.all(ids.map(performAsyncOperation));
  + for (const id of ids) {
  +   await performAsyncOperation(id);
  + }
  const end = Date.now();
  console.log(`All operations performed in ${end - start}ms, moving on to something else now.`);
}

Which, if we run this script, gives the following output:

[tim@praxis ~]$ node limit-async.js
Performed operation for resource 1.
Performed operation for resource 2.
Performed operation for resource 3.
...
Performed operation for resource 97.
Performed operation for resource 98.
Performed operation for resource 99.
All operations performed in 29825ms, moving on to something else now.

As we'd expect, every operation awaits for the previous one to be completed, and, in a way, we found a succesful solution to our problem.
However, one would probably argue this being far from optimal, and that the system against which we run these asynchronous operations can safely withstand up to 3 concurrent operations, thus, our script could theoretically be ~3 times faster.

The solution: limiting concurrency using workers #

Now, let's take a look at how we can update our script to perform at most 3 operations concurrently.
For that, let's introduce a worker function, to which we will delegate the job of performing one asynchronous operation at a time.

const worker = (next_) => async () => {
  let next;
  while ((next = next_())) {
    await performAsyncOperation(next);
  }
};

Note: such a worker function can be implemented in various ways, this implementation is just an example of what I've used in the past.

However big the number of asynchronous operations we wish to perform, we will ever need at most, 3 concurrent workers.

const CONCURRENT_WORKERS = 3;

We will then want to give a way to our workers to retrieve the next resource identifier, or thing, to perform the asynchronous operation from.

const workers = [];
for (let i = 0; i < CONCURRENT_WORKERS; i++) {
  const w = worker(ids.pop.bind(ids));
  workers.push(w(ids));
}

Let us update our script:

function performAsyncOperation(id) {
  return new Promise((resolve) => {
    setTimeout(() => {
    console.log(`Performed operation for resource ${id}.`);
    resolve();
    }, 300);
  });
}

const worker = next_ => async () => {
  let next;
  while ((next = next_())) {
    await performAsyncOperation(next);
  }
};

const CONCURRENT_WORKERS = 3;

async function run() {
  const start = Date.now();
  const ids = Array.from(Array(99), (_, i) => i + 1);

  const workers = [];
  for (let i = 0; i < CONCURRENT_WORKERS; i++) {
    const w = worker(ids.pop.bind(ids));
    workers.push(w(ids));
  }

  await Promise.all(workers);

  const end = Date.now();
  console.log(`All operations performed in ${end - start}ms, moving on to something else now.`);
}

run();

And run it:

[tim@praxis ~]$ node limit-async.js
Performed operation for resource 1.
Performed operation for resource 2.
Performed operation for resource 3.
...
Performed operation for resource 97.
Performed operation for resource 98.
Performed operation for resource 99.
All operations performed in 9948ms, moving on to something else now.

Bonus solution: batching concurrent operations #

There's one more way to look at the problem, and reach another solution: splitting the asynchronous operations to be performed in batches.
In our case, if we have 99 operations to perform, we can split these into 33 batches of 3 operations.
With batching, every operation within one batch will be performed conccurently, and the next batch will only be started once the previous one is finished.
How does one implement concurrent tasks batching with JavaScript?

async function run() {
  const start = Date.now();
  const ids = Array.from(Array(99), (_, i) => i + 1);

  - await Promise.all(ids.map(performAsyncOperation));
  + let i = 1;
  + while (ids.length) {
  +   await Promise.all(ids.splice(0, 3).map(performAsyncOperation);
  +   console.log('Performed async operactions batch number', i);
  +   i++;
  + }
  const end = Date.now();
  console.log(`All operations performed in ${end - start}ms, moving on to something else now.`);
}

Which gives us the following output:

[tim@praxis ~]$ node limit-async.js
Performed operation for resource 1.
Performed operation for resource 2.
Performed operation for resource 3.
Performed async operactions batch number 1
...
Performed operation for resource 97.
Performed operation for resource 98.
Performed operation for resource 99.
Performed async operactions batch number 33
All operations performed in 9981ms, moving on to something else now.

Conclusion #

Asynchronous JavaScript can be tricky, and though one may argue the language lacks high-level APIs to deal more efficiently with some of these tricky cases like the one we've just covered, it's always worth taking our chance at solving the problems leveraging the features that we're provided by the language.

In this post we've built and lived through a common scenario of managing asynchronous operations concurrency in JavaScript, along with a common pitfall associated with a naive approach, as well as an intermediary solution that is also very useful on some other cases, and finally the optimal solution for dealing with this problem, all without using third party modules. I hope this may be useful to some of you, and that I did not take too many shortcuts in the process.

If you liked this post, feel free to encourage me by saying so on my Twitter and/or by liking/retweeting the associated tweet or sharing the article around you.
Finally, feel free to share your feedback if you have ideas or know how I can improve this post or this blog, thank you :)

Note: special thanks to baloo for teaching me this trick while I was hacking together a script purposed to pre-fill HTTP cache server entries for a given website from its sitemap file.

Setting up this blog (quickly) with Eleventy.

2020-08-06T00:00:00+00:00

Hey, welcome! #

I've been wanting to have a tech blog of my own I could write on for a while now...
And so I have tried to set one up a few times over the years, always with the same goals:

not rely on a third party platform such as Medium and the like
not code it all myself, because who's got time for that

All my previous attempts failed, roughly at the same stage, whether it was full-features CMSs such as Wordpress or Ghost, or static site generators such as Gatsby. Every time, something felt off: it would require too much work for me to get what I wanted, or, more accurately: it would require too much work for me to get rid of all the stuff that I did not want.

Here are a few examples of things I do not want:

node_modules bloat
JavaScript / markup bloat
client-side rendering
complicated webserver runtime, database engine
overly complex APIs & tooling
etc...

Paradoxically (or, is it?), it is now that I have much more time on my hands that I have found the way forward.

Eleventy (11ty), a simpler static site generator #

I have been hearing about Eleventy (11ty), a simpler static site generator for quite some time now and decided to give it a spin.
Immediately upon opening Eleventy Documentation, I stumbled upon the Starter Projects, and more specifically, the eleventy-base-blog starter project. Skipping further reading of the documentation, let's take a look at the steps I followed that led me to having this blog ready for ~production within a few hours.

This is a not a tutorial #

Register a domain name first, as any good procrastinator with a side-project idea would
Clone eleventy-base-blog starter project:

$ cd Repositories
$ git clone git@github.com:11ty/eleventy-base-blog.git timtech.blog

Start the development server:

$ cd timtech.blog
$ npm install
$ npm start

Fiddle with the Nunjucks templates, the CSS file
Add a webfont: Fira Sans
- downloaded as .tff from Google Fonts
- exported to .woff2 (+ subsetting, etc...) using Font Squirrel
Fiddle some more .eleventy.js, package.json files and other stuff
Write this post in Markdown
Create a GitHub repository
Set git remote, commit, push:

$ rm -rf .git
$ git init
$ git remote add git@github.com:ziir/timtech.blog.git
$ git add .
$ git commit -m "initial commit"
$ git push origin master

And... voila! (conveniently leaving out the deploy & hosting part)

Now, is this blog perfect? #

Absolutely not, it's just the bare minimum for me to push my content out there.

What about Eleventy, is it good? #

The fact that I was able to hack together a decent blog out of it without being familiar with it or reading any documentation puts it in a good position I believe.
There's one thing in particular that I appreciate of Eleventy: I mentionned earlier that the other options I had tried previously didn't satisfy me and, in some way, would be forcing too much work on me to remove all of the stuff that I did not want, and so far, Eleventy hasn't given me any of those.

What next? #

Now begins the journey of this blog, built with Eleventy. There's a bunch of things that this blog is currently missing and that I am fairly confident I will be able to implement with ease using Eleventy:

a search feature, even as a static site
pagination
some sort of a comments system
an original webdesign
Tailwind CSS, because I love utility-first
offline-first PWA
more stuff I'll make up along the way

What if Eleventy is not up to the task? #

If, for some reason, I am not satisfied by Eleventy for the purposes of this blog, moving away from it to some other tool should be pretty easy.
Let's take a look of the things I would want to keep in such a scenario:

/posts/:slug, /tags/:tag, /about, etc... URLs & associated content
JSON / Atom feeds
a sitemap
and... that's it!

Wrapping things up #

While it's usually best to weigh the pros and cons of available options before committing to either of them, sometimes it really is fine to just try it, move forward and adapt along the way, even if the first results are far from perfection.

Tim's Tech Blog

React Server Components, without a framework?

Introduction #

RSC Survival Guide #

Disclaimer #

React Client Components #

The React Server Components Model #

React Server Components Announcements Timeline #

React Server Components #

A quick note on “React SSR” #

React Shared Components #

'use server' & 'use client' directives #

'use client' #

'use server' #

Suspense & Error Boundaries #

use() #

Demo: migrating a React Notes App to RSC without a framework #

A take-home technical assignment backstory #

A React Notes App (2020) #

Actually migrating a CRA React Notes App to RSC with no framework (2023)

Disclaimer #

Inspiration #

RSC Notes App Demo / Playground #

Objectives #

Dependencies #

React Canary #

React Server & React Flight APIs #

react-server-dom-webpack/plugin #

Example Usage #

react-server-dom-webpack/node-register #

Example Usage #

renderToPipeableStream from react-server-dom-webpack/server #

Example Usage #

createFromReadableStream from react-server-dom-webpack/client #

Example Usage #

createFromFetch from react-server-dom-webpack/client #

Example Usage #

Our first React Server Component #

Server-Side Rendering of Server Components #

An Unorthodox SSR Implementation #

Traditional SSR Store Serialization #

Server Components React Flight Output Serialization #

Inlining Server Components Output into the HTML Shell #

Rendering Server Components Output on the Client #

Data-Fetching in Server Components #

Adding Data-Fetching with async / await #

Data-Fetching in child components: waterfall? #

Moving the async/await down #

Suspense-enabled streaming #

With async/await #

use() vs async/await #

Passing the Server's pending Promise to the Client #

use() the force, Luke #

Waterfall waterfall waterfall #

Routing with Server Components? #

Form handling with Server Components #

React Client Actions #

Should you be writing your own RSC framework? #

Should you be migrating your Full-Stack React Framework to RSC? #

Going further with RSC #

server-only & client-only packages #

React taint APIs #

React Server & Client Actions #

Announcements #

Ecosystem #

Philosophy #

Thanks for reading! #

TypeScript Legacy Experimental Decorators with Type Metadata in 2023

TL;DR #

Problem #

The Old Ways #

Why not compile for production using Babel? #

Times have changed, expectations too #

Anyway #

TypeScript Legacy / Experimental / Stage 2 Decorators (experimentalDecorators) #

Decorators Type Metadata (emitDecoratorMetadata / Reflect.metadata / reflect-metadata) #

Vite? #

Vitest? #

TypeScript Legacy Experimental Decorators with Type Metadata with Vite? #

The best compiler for TypeScript Legacy Experimental Decorators with Type Metadata? #

`'use server'` & `'use client'` directives #

`'use client'` #

`'use server'` #

`use()` #

`react-server-dom-webpack/plugin` #

`react-server-dom-webpack/node-register` #

`renderToPipeableStream` from `react-server-dom-webpack/server` #

`createFromReadableStream` from `react-server-dom-webpack/client` #

`createFromFetch` from `react-server-dom-webpack/client` #

Adding Data-Fetching with `async` / `await` #

Moving the `async`/`await` down #

`use()` the force, Luke #

SWC adds `.js` file extension to relative module imports #