Here's an input. You can tell because it's got a border.

This border is just a solid grey colour: hsl(0 0 75). I think it looks pretty nice as is, but there are some situations where it will struggle.

For example on a gradient background:

Now the grey border looks muddy and hard to see. That light grey doesn't stand out from the background at all. We'd need to make the border darker to be properly visible here. Let's make it 25% darker with hsl(0 0 50%) and see how that looks:

This is better, but it's going to be annoying to manually set the border colour of our input every time we use it on a coloured background. It would be nice if we could make one version of the border that worked on any background.

Luckily we can, by using a semi-transparent border. This will allow some of the background colour to show through, which will make the border naturally appear darker on darker backgrounds. It will also slightly tint the border colour so it matches better.

Let's try setting the border to a transparent grey like hsl(0 0 0 / 0.25). This is pure black but at 25% opacity, so it should be equivalent to our 75% lightness original grey colour.

It looks pretty much identical on a white background. Let's put the original back in so we can compare:

Now let's see if it looks better on our gradient background:

That's weird, it hasn't helped at all! It turns out that by default the background of an element extends up to the edge of its "border box".

That means the white background of the input is "underneath" the transparent border. This isn't what we want—for this trick to work we need the gradient background to show through the border.

Luckily there's a CSS property to control where an element's background extends to: background-clip. By default this is set to border-box, but we can change it to padding-box to tell the browser to stop drawing the input's background at the edge of the padding, before the border starts. Let's see how that looks:

How much better does that look? Our input will stay distinct from the background no matter what.

There is another edge-case that we need to account for: shadows. Let's see how our inputs look with a nice shadow under them.

That's annoying. Our borders blend into the shadow and disappear at the bottom. This makes the inputs look kind of weird and bad again.

I was initially confused about why the input with the transparent border looks the same here. Surely it should work the same as with the gradient background? Unfortunately it turns out that CSS box-shadows always start being drawn after the border-box of an element. As far as I can tell there's no way to make the shadow start after the padding-box (underneath the border).

Here's a visualisation of the problem:

The border colour is transparent black, so the gradient background shows through and tints it green. However the red box-shadow doesn't show through—it starts after the border-box, and as far as I can tell there's no way to change this.

In order to work around this we have to stop using borders for our border. We need something that will render outside the element, so it sits on top of the box-shadow. Our two options are either outline, or more box-shadow.

Outline is by far the easiest to work with, since the syntax is the same as for borders. We can set outline-color: hsla(0, 0%, 0%, 0.25) and get the same result as before:

This looks so much better with the shadow. The edge of the input is crisp, even right at the bottom where it meets the shadow. And it still looks great on the gradient background too:

The downside to using an outline as a border is you can't also have an outline. For example if you wanted a more distinct separate focus style you'd be a bit stuck here.

It's more complicated, but you can also simulate a border using box-shadow. You set zero offset and blur, and use the spread to control the thickness. For example: box-shadow: 0 0 0 1px hsl(0 0 0 / 0.25).

This looks good on the gradient background too:

The only downside to this approach is that it's more fiddly to add another shadow, since we need to write multiple box-shadows. For example:

input {
    box-shadow:
        /* The border */
        0 0 0 1px hsl(0 0 0 / 0.25),
        /* The actual shadow */
        0 10px 15px -3px hsl(0 0 0 / 0.2),
        0 4px 6px -4px hsl(0 0 0 / 0.2)
}

And finally, putting everything together, let's see how it looks on the gradient background with a shadow:

I love it! Some might argue that this is a lot of effort to go to for a pretty subtle enhancement, but I think that sweating the small UI details is what makes really great products stand out. You only have to write these styles once, but every time a user sees them they pay off.

One final bonus tip: if you're writing Tailwind this is as simple as switching from the border class to ring.

cache-control: max-age=3600

will be cached for one minute (3600 seconds)

A one minute cache is not going to improve performance much though, since most users will visit the site again more than one minute later, leading to them waiting for the file to re-download.

We can't just set a much longer cache time, because we want the user to receive updates to this file. If we set a one year cache time the user will be stuck with the old file for that long.

Moder build tooling generally supports cache-busting using file hashes. When your app builds each static file will have a hash of the contents added to the filename. For example main.js might become main-50b6a13c.js. This hash will be the same as long as the file's contents are the same, but will change if a single character is different.

This lets us set files to cache effectively forever, since every version of our file is unique and immutable. Browsers generally won't cache for longer than one year:

cache-control: max-age=604800, immutable

The immutable directive tells the browser to never even try to revalidate this response—it should never be different.

This is fantastic for performance, as now each user will only ever load each version of your app once. Every time they load the page the browser will instantly have access to all the static resources without having to wait for a response from your server.

There is still one downside: if any of our code changes the browser must re-download the entire file. Luckily we can mitigate this by splitting out our dependency code from our own.

When building modern JS apps it's common to have a large quantity of your code come from 3rd party dependencies. For example my Reddit app requires 228kb of JS, 207kb of which is just React, React Router and Valibot. These dependencies rarely change, and I am in control of when I update them. If we split these into their own separate JS file we can avoid invalidating the cache for all this every time we change our own code. The dependencies will be cached until one of them is updated.

Each build tool has a different way of configuring "vendor chunks", but here's how to do it in Vite:

// vite.config.js
import { defineConfig, splitVendorChunkPlugin } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
    plugins: [react(), splitVendorChunkPlugin()],
    server: { port: 3000 },
    build: { target: "esnext" },
});

We import the splitVendorChunkPlugin and add it to the config's plugins array. That's it. Here's the output of vite build before adding the plugin:

✓ 54 modules transformed.
dist/index.html                      0.69 kB │ gzip:  0.46 kB
dist/assets/index-e032778f.css      10.35 kB │ gzip:  3.25 kB
dist/assets/missing-c45c8138.js      0.28 kB │ gzip:  0.22 kB
dist/assets/media-05d37584.js        1.67 kB │ gzip:  0.87 kB
dist/assets/media-bb4a63f2.js        2.12 kB │ gzip:  0.94 kB
dist/assets/post-3a754864.js         2.32 kB │ gzip:  1.04 kB
dist/assets/subreddit-f9f8913a.js    3.10 kB │ gzip:  1.39 kB
dist/assets/error-b1adb144.js        5.45 kB │ gzip:  1.91 kB
dist/assets/comments-ca3ad949.js     7.23 kB │ gzip:  2.86 kB
dist/assets/index-75cd0051.js      212.78 kB │ gzip: 68.89 kB
✓ built in 899ms

Note the index.js file at the bottom that is 212.78kb.

Here's after adding the plugin:

✓ 54 modules transformed.
dist/index.html                      0.76 kB │ gzip:  0.48 kB
dist/assets/index-e032778f.css      10.35 kB │ gzip:  3.25 kB
dist/assets/missing-7ecbefcc.js      0.28 kB │ gzip:  0.22 kB
dist/assets/media-0f91f393.js        1.70 kB │ gzip:  0.89 kB
dist/assets/media-a9720384.js        2.16 kB │ gzip:  0.96 kB
dist/assets/post-65a175ad.js         2.36 kB │ gzip:  1.06 kB
dist/assets/subreddit-5fe07416.js    3.12 kB │ gzip:  1.41 kB
dist/assets/error-9e227f5f.js        5.46 kB │ gzip:  1.91 kB
dist/assets/index-f485a835.js        6.58 kB │ gzip:  2.64 kB
dist/assets/comments-af5f5540.js     7.26 kB │ gzip:  2.87 kB
dist/assets/vendor-fdd8423a.js     206.54 kB │ gzip: 66.64 kB
✓ built in 921ms

We now have a vendor.js that is 206.54kb. That's the vast majority of our original bundle split into a file that will never change until I update a dependency, meaning users will rarely have to re-download any of it.

We're going to implement a very simplified version of a testing library for React that is based on the very popular React Testing Library, so we can better understand what this dependency does for us.

How components work

There are two main steps to rendering a React component so we can test it. First we need to convert JSX syntax to regular JS, then we need to convert React's object representation of the UI into real DOM elements we can interact with.

For example this component:

function Greeting() {
    return <h1>Hello</h1>;
}

looks like this when converted to JS:

import { jsx as _jsx } from "react/jsx-runtime";

function Greeting() {
    return _jsx("h1", { children: "Hello" });
}

When called this function returns an object that looks something like this:

{
    "$$typeof": Symbol("react.element"),
    "props": { "children": "Hello" },
    "type": "h1",
}

We can't really do much with this object other than assert that its props are correct. However this wouldn't be a very helpful test since we're passing those props in ourselves.

React components need to be rendered into a DOM using the render method. We create a "React root" for rendering elements into, then render our component into it:

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

let div = document.querySelector("#root");
let root = createRoot(div);
root.render(<Greeting />);

In this case we're assuming we have access to a document that contains a div with an ID of "root". That leads us to another problem.

Environment setup

Most testing environments do not have access to a DOM. For convenience we usually like to runs tests from our terminal, or in a CI job when we push a PR to GitHub. It is possible to run tests in a real browser (e.g. using QUnit), but almost nobody does anymore.

So to test React components we need to create a fake DOM within our testing environment. This usually means using the JSDom library. I've written about using JSDOM before, so I won't go into detail now. Suffice to say it implements a large number of browser features in pure JavaScript so we can run code that is meant for the browser in Node or some other non-browser environment.

The simplest way to use JSDOM is via the global-jsdom package. This sets up a DOM and all the globals you would expect to use in the browser (window, document, console etc). It's as simple as importing a file:

import "global-jsdom/register";

Dealing with JSX

Node doesn't understand JSX syntax. There are a couple of ways to deal with this: either compile your code in advance with something like esbuild or Babel, or use a Node module hook to compile it on the fly as you import it.

To make things simpler here we're going to use the Bun runtime, which supports JSX natively.

Rendering components

Now that we have a DOM we can render our component as above:

import "global-jsdom/register";
import { createRoot } from "react-dom/client";

function Greeting() {
    return <h1>Hello</h1>;
}

let div = document.querySelector("#root");
let root = createRoot(div);
root.render(<Greeting />);

console.log(div.innerHTML); // <h1>Hello</h1>

Writing a render function

It would be nice to abstract some of this rendering boilerplate so that testing looks as simple as this:

import { test, expect } from "bun:test";
import { render } from "./helpers.js";

test("Greeting renders correctly", () => {
    render(<Greeting />);
    let h1 = document.querySelector("h1");
    expect(h1).toBeInstanceOf(HTMLHeadingElement);
});

We want to write a render function that does three things:

1. Create a new div element to render into
2. Put the div in the DOM
3. Render our React element into a new React root

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

export function render(element) {
    let container = document.createElement("div");
    document.body.append(container);
    let root = createRoot(container);
    root.render(element);
}

If we run the example test from above it will fail:

Expected constructor: [class HTMLHeadingElement]
Received value: null

This is strange because everything should work fine now. If we try to log document.body.innerHTML after we call render we just get <div></div>. This implies that the container is being created and appended to the body, but the React root is not rendering.

Newer versions of React render asynchronously, which means we cannot rely on the render having completed before the rest of our code runs. We can verify that this is the problem by making our test async and awaiting a promise to push our test code to the back of the queue:

test("Greeting renders correctly", async () => {
    render(<Greeting />);
    await new Promise((resolve) => setTimeout(resolve, 0));
    console.log(document.body.innerHTML);
    let h1 = document.querySelector("h1");
    expect(h1).toBeInstanceOf(HTMLHeadingElement);
});

The test now passes, and the log shows the correct DOM containing the <h1>. This isn't really a proper solution though, just a hack to diagnose the issue. Luckily React provides a way to fix this.

Using the act function

The React team realised that tests would need a way to reliably render components and assert about them synchronously, so they provided the act function. React will make sure any any pending updates for the code wrapped in act are complete before the rest of your test code runs. We'll need to use act any time we render, or trigger state updates or effects.

We need to update our render function to wrap the React render in act:

export function render(element) {
    let container = document.createElement("div");
    document.body.append(container);
    let root = createRoot(container);
    act(() => root.render(element));
}

We can now get rid of the timeout in our test and see that it passes correctly:

test("Greeting renders correctly", () => {
    render(<Greeting />);
    console.log(document.body.innerHTML);
    let h1 = document.querySelector("h1");
    expect(h1).toBeInstanceOf(HTMLHeadingElement);
});

It also logs the correct DOM:

<div><h1>Hello</h1></div>

We now have a warning in the console from React:

Warning: The current testing environment is not configured to support act(...)

The act function is designed to only be used in testing environments, not real apps. So we need to tell React that this code is running inside a test, by setting a special global variable.

global.IS_REACT_ACT_ENVIRONMENT = true;

export function render(element) {
    // ...
}

That's it as far as rendering goes. We can now render components and use normal DOM methods to query elements and make assertions about them.

Cleaning up after ourselves

Since the DOM is global every test is updating the same document. This could potentially cause one test to affect the result of another, which is a bad idea. Tests should always be isolated from each other so that when one fails you know it's a real failure and not a false negative caused by some other test.

If we add a second test that also logs the DOM we can see this accumulation:

test("Another thing renders correctly", () => {
    render(<span>goodbye</span>);
    console.log(document.body.innerHTML);
    let h1 = document.querySelector("h1");
    expect(h1).toBeInstanceOf(HTMLHeadingElement);
});

This test logs:

<div><h1>Hello</h1></div>
<div><span>goodbye</span></div>

The test also passes even though it shouldn't! We are searching the DOM for an h1 and finding it, even though we rendered a span, because the h1 is still there from the previous test.

We need to create a way to clean up the DOM to remove any containers we've added, and to unmount any React roots we created. Most testing frameworks provide a way to run code after each test, so we can aim for something like this:

import { test, expect, afterEach } from "bun:test";
import { render, cleanup } from "./helpers.js";

afterEach(cleanup);

We'll have to keep track of both the container and React roots we create during renders, so lets push them into an array:

let roots = [];

export function render(element) {
    // ...
    roots.push({ root, container });
}

Then we can write a cleanup function that loops over this array and deletes any DOM nodes and unmounts any React roots:

export function cleanup() {
    for (let { root, container } of roots) {
        act(() => root.unmount());
        container.remove();
    }
    roots.length = 0; // empty the array once we're done
}

Note that just like when we render into a React root, we also wrap the unmount in act to make sure it happens at the right time.

Now when we run our two tests again the second one fails as it should, since the DOM only contains the span:

<div><span>goodbye</span></div>

Dispatching events

Writing useful component tests requires interacting with them. Otherwise you're just verifying that you typed the right JSX. In order to test interactivity we need to be able to trigger events on the DOM elements the component rendered.

Let's try to test this counter component:

function Counter() {
    let [count, setCount] = useState(0);
    return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

First we need to render it as before:

test("Counter can increment", () => {
    render(<Counter />);
    let button = document.querySelector("button");
    if (!button) throw new Error("could not find <button>");
    expect(button.textContent).toBe("0");
});

To verify that the counter works we need to trigger a click event on the button element, then check that the text content has updated. We can do that using the dispatchEvent method on DOM elements:

test("Counter can increment", () => {
    render(<Counter />);
    let button = document.querySelector("button");
    if (!button) throw new Error("could not find <button>");
    expect(button.textContent).toBe("0");

    let click = new MouseEvent("click", { bubbles: true });
    button.dispatchEvent(click);
    expect(button.textContent).toBe("1");
});

However this test fails: the text content does not update from "0" to "1". We do get a helpful warning from React though:

Warning: An update to Counter inside a test was not wrapped in act(...).

When testing, code that causes React state updates should be wrapped into act(...)

This is the same problem as before—state updates are not handled synchonously, so our assertions run before React has finished re-rendering. We need to wrap the event dispatch in act to ensure everything happens in the right order:

test("Counter can increment", () => {
    // ...
    let click = new MouseEvent("click", { bubbles: true });
    act(() => button.dispatchEvent(click));
    expect(button.textContent).toBe("1");
});

Now the DOM updates correctly and the test passes.

Creating and dispatching events like this is a little clunky. It would be nice to abstract this away into a helper function like this:

fireEvent("click", button);

Unfortunately that is not a simple undertaking. Different events require different constructor functions (i.e. "click" events must use MouseEvent, "blur" events must use FocusEvent etc). Different events also need different options: some bubble and some do not. React Testing Library maintains a ~400 line object mapping each event type to the required options to handle this.

The best we can do without adding a ton of complexity is hide the act call so tests don't need to import this from React:

export function fireEvent(event, element) {
    act(() => element.dispatchEvent(event));
}

This simplifies the test very slightly:

test("Counter can increment", () => {
    // ...
    let click = new MouseEvent("click", { bubbles: true });
    fireEvent(click, button);
    expect(button.textContent).toBe("1");
});

Input value updates

There is another weird edge-case to take care of. React does some strange things when handling updates to the values of inputs and textareas. This makes normal event dispatches not work correctly. For example:

function Uppercase() {
    let [value, setValue] = useState("");
    return (
        <input
            value={value.toUpperCase()}
            onChange={(e) => {
                console.log(e);
                setValue(e.target.value);
            }}
        />
    );
}

test("Counter can increment", () => {
    render(<Uppercase />);
    let input = document.querySelector("input");
    if (!input) throw new Error("could not find <input>");

    input.value = "hello";
    let change = new Event("change", { bubbles: true });
    fireEvent(change, input);
    expect(input.value).toBe("HELLO");
});

This test fails because the change event handler never runs (we never see the event logged by the component). There's a discussion on why this happens from 2017. Unfortunately the solution is pretty weird. This is the most minimal version I can get to work:

function setValue(element, value) {
    let proto = Object.getPrototypeOf(element);
    let setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
    if (setter) setter.call(element, value);
}

We find the prototype of the input element, then get the setter function for the value property and then bind it to the input element and call it with the new value we want to set. This bypasses React's hijacking of the update so the event handler actually runs.

We have to use this instead of setting the value directly on the input:

test("Counter can increment", () => {
    // ...
    setValue(input, "hello");
    let change = new Event("change", { bubbles: true });
    fireEvent(change, input);
    expect(input.value).toBe("HELLO");
});

Even weirder this works fine in Jest with their JSDOM setup, but not in Bun using global-jsdom. This is another argument for using React Testing Library, since they have a more robust implementation of this.

Conclusion

Here's our final set of testing helpers:

import "global-jsdom/register";
import { act } from "react";
import { createRoot } from "react-dom/client";

global.IS_REACT_ACT_ENVIRONMENT = true;

let roots = [];

export function render(element) {
    let container = document.createElement("div");
    document.body.append(container);
    let root = createRoot(container);
    act(() => root.render(element));
    roots.push({ root, container });
}

export function cleanup() {
    for (let { root, container } of roots) {
        container.remove();
        act(() => root.unmount());
    }
    roots.length = 0;
}

export function fireEvent(event, element) {
    act(() => element.dispatchEvent(event));
}

export function setValue(element, value) {
    let proto = Object.getPrototypeOf(element);
    let setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
    if (setter) setter.call(element, value);
}

This hopefully demystifies React testing a bit—there's not much magic happening; it's mostly just regular DOM stuff with a few weird bits due to React's strange internals.

My main takeaway would be to just use React Testing Library, since it handles a lot of edge-cases for you and provides lots more convenient helpers too.

If you just want the tl;dr solution: use <link rel="preload"> to make the browser kick off fetch requests before it even starts downloading your JS files. That way the responses are ready by the time your app code runs.

The problem

One of the major downsides to a single-page app is that data fetching doesn't begin until your app's JavaScript runs. Depending on the size and complexity of the app it can be a non-trivial amount of time before your code actually calls fetch.

A typical "naive" client-side React app with a bunch of dependencies chosen by popularity (or at random) can easily end up loading over 1MB of JavaScript. If the first thing the app does is fetch some JSON from an API so that it can actually render content, that means the browser must:

1. Download and parse the (mostly empty) HTML
2. Find the script tag(s) containing the app's JavaScript code
3. Download, parse and execute all the JavaScript
4. Execute any fetch requests it finds
5. Update the DOM once the requests are complete

That 1MB+ of JS will take a while to download (especially on 3G), and potentially even longer to run (especially on mobile, since lots of Android phones have terrible single-core CPU performance). The user will be staring at a blank white screen (or maybe a janky loading spinner) while they wait.

"In fact, of the total time a page spends loading in a browser like Chrome, anywhere up to 30% of that time can be spent in JavaScript execution"
The cost of JavaScript in 2019, V8 Blog.

The solution

Web browsers have a declarative API for preloading resources. You may have used this before for loading fonts or something to make sure your CSS doesn't block rendering. Well it turns out you can use the same API for preloading arbitrary JS fetch calls.

Here's a fetch to get the first 20 Pokémon from the PokéAPI:

fetch("https://pokeapi.co/api/v2/pokemon");

Here's the exact same request triggered declaratively in HTML:

<link
    rel="preload"
    href="https://pokeapi.co/api/v2/pokemon"
    as="fetch"
    crossorigin
/>

When the browser parses the <link> tag in the HTML it will queue a request for that resource, then cache the response. If your JS code requests the same resource within a few seconds the browser will give it the cached version.

This means the browser can be fetching your API responses while it is still downloading your JS code, which can be a pretty big speedup if your JS is slow.

Caveats

It's important not to abuse this. If you preload something but don't use it within a few seconds the browser will put a big warning in the console. You've just wasted the users bandwidth, and potentially slowed down the page load by having the browser spend time fetching something it didn't need.

The preload must match what you fetch exactly. If the requests are even a bit different the browser won't be able to match them and you'll see the same warning about not using a preloaded resource.

This is why we needed the crossorigin attribute in our example. The <link> tag doesn't use CORS by default because it's not needed for e.g. CSS files. However JS fetch requests have CORS enabled, so we need to specify it in the preload to match.

Practical example

I built a quick example to try and get some data on exactly how much this might help. Here's a simple JS app that lists Pokémon from the PokéAPI:

<ul id="list">
    <!-- pokemon go here -->
</ul>
<script>
    fetch("https://pokeapi.co/api/v2/pokemon")
        .then((res) => res.json())
        .then(async (json) => {
            let pokes = await Promise.all(
                json.results.map(async (p) => {
                    let poke = await fetch(p.url).then((res) => res.json());
                    let li = document.createElement("li");
                    li.append(poke.name);
                    return li;
                })
            );
            list.replaceChildren(...pokes);
        });
</script>

Here's how the page renders:

1. Browser downloads and starts parsing the HTML
2. Browser finds the script and starts parsing the JS
3. JS starts fetching the list of 20 Pokémon
4. JS waits for promise to resolve
5. JS starts fetching each of the 20 Pokémon
6. JS waits for all 20 to resolve
7. JS updates DOM

Initial performance

In this case performance is pretty good. Our JS is inline, which means the browser doesn't have to make a separate HTTP request to download it. There's also hardly any of it, so it won't take long to parse and execute. We're also not accidentally fetching all the Pokémon serially, which is easy to do with await.

If I simulate a "Slow 3G" connection this page fully renders in 8.58s in Edge. Here's a visualisation of the requests:

/index.html (2.01s)
                  └─ /pokemon (2.10s)
                                    ├─ /pokemon/1 (3.71s)
                                    ├─ /pokemon/2 (3.84s)
                                    ├─ /pokemon/1 (4.37s)
                                    ├─ ...etc

The HTML is done downloading in 2.01s, but the first fetch isn't queued until 2.05s after we start loading the page. That means it takes the browser 40ms to get ready to send the fetch, with this tiny amount of inlined JS.

Make it realistic (slower!)

We can simulate slower loading JS by putting a 2s timeout in the code. This will act as if we have a larger JS file to download. Note that this is probably unrealistically fast: if the 670B (0.00067MB) HTML file is taking 2.01s to download imagine how long a 1MB JS bundle will take to download, parse and execute.

With a 2000ms setTimeout wrapped around the JS code the page now fully renders in 10.47s. This is roughly 2s slower than previously, which is what we'd expect. The HTML still loads in 2.01s, but the first fetch now doesn't start until 4.05s in. This is exactly 2s slower than before.

Fix it with preload

Now lets try preloading our fetch requests. We can do this by adding <link> tags for each request to the HTML. In this case we need 21: one for the initial list request and one for each of the 20 pokémon requests.

This page now fully renders in 6.69s. This is not only 4s faster than the setTimeout example, but still 2s faster than the initial version. If we visualise the requests we can see why:

/index.html (2.06s)
                  ├─ /pokemon   (2.03s)
                  ├─ /pokemon/1 (3.82s)
                  ├─ /pokemon/2 (3.79s)
                  ├─ /pokemon/1 (3.89s)
                  ├─ ...etc

The initial HTML load took a bit longer because adding all those <link> tags made it grow from 670B to 2.7KB. However because the browser knows about all the data dependencies up front it can start downloading them all in parallel. This means that not only do we avoid the 2s delay waiting for the JS to execute, we also skip the 2.03s it took for the list of pokémon to download. That explains why the total load time was about 4s faster.

In summary

Obviously this technique will only work if you can know your data dependencies statically ahead of time. If your page needs some dynamic information (like localStorage state) to render then this technique won't work. However if you can make it work it feels like a no-brainer to leverage built-in browser primitives to speed up your single-page apps.

Update (May 2026): I published an improved version of this JSX renderer as part of my server-side app library.

What is JSX?

JSX is an extension to JavaScript that lets you write HTML-like syntax, which would usually be invalid. This was invented for React, to make it easier to create DOM elements declaratively:

<h1 id="my-title">Hello world</h1>

JSX also provides a nice developer experience. Since it's embedded within JS you just use JS features to generate elements. I like not really having to shift mindsets as I jump from business logic to UI code. The popularity of React means JSX has great tooling support. For example syntax highlighting, autocompletion, warnings about accessibility errors.

That said, as much as I like JSX I don't want to write all my apps as React SPAs. Nowadays I default to simple server-rendered apps. However I do still like using JSX to render HTML strings. This is nicer than using template literals, since they're just unstructured strings with none of the benefits listed above. It's also harder to compose components together, since function calls don't look like HTML. For example:

html`
  <header>
    ${Title({ children: "Hello" })}
    <p>world</p>
  </header>
`

<header>
  <Title>Hello</Title>
  <p>world</p>
</header>

How JSX works

We need to understand what's actually going on before we can write our own renderer. JSX is one of those things that seems magical because several things combine to create a smooth experience. In a standard React app rendering is a 3-step process:

1. JSX is "transpiled" to regular JS functions by a bundler
2. The function calls return objects
3. A special render function converts the object tree to DOM

Here's an example:

let title = <h1>hello</h1>;
console.log(title);

We can't run this in the browser since JSX isn't valid JS. So we'll use esbuild to transpile it (convert it to actual JS):

import { jsx } from "react/jsx-runtime";
let title = jsx("h1", { children: "hello" });
console.log(title);

You can see that JSX directly converts to simple functions. We can configure exactly what library the import comes from if we like, but for now let's stick with React. If we run this code we get this log output:

{
  "type": "h1",
  "key": null,
  "ref": null,
  "props": {
    "children": "hello"
  },
  "_owner": null,
  "_store": {}
}

All the jsx function does is scaffold a simple object describing the element. If we had a more complex UI this object would have more objects nested inside the children property.

You can see that React's jsx implementation really doesn't do much more than construct a simple object (plus a bunch of dev-only checks).

Finally to put DOM elements on the page we would use React's render method to convert this object tree to real DOM elements on the page:

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

let title = jsx("h1", { children: "hello" });
createRoot(document.querySelector("#root")).render(title);

If instead we wanted to render an HTML string on the server we could do this:

import { renderToString } from "react-dom/server";

let title = jsx("h1", { children: "hello" });
let html = renderToString(title);
// "<h1>hello</h1>"

This two-step process is necessary because React uses a virtual DOM for rendering. This lets it compare the previous and next object trees to figure out just the bits it needs to update, so it doesn't have to change more of the DOM than necessary.

However on the server this overhead is not necessary, since our responses are one-off strings that get sent and never change. I was inspired by kitajs/html, which skips the render step entirely and just has a jsx function produce a string directly. Their code looks pretty complex though (I imagine for good reason), so I did what I always do and wrote my own way simpler version.

Building my own

Let's define our requirements by checking how different snippets of JSX are transpiled by esbuild. We can then write tests to make sure our code works, make the test pass, then add more features. TDD!

Here's the simple case:

<h1>Hello</h1>;
// ↓
jsx("h1", { children: "Hello" });

We need a jsx function that takes the tag name as a string, then an object containing the children as a string. We want this to return a string of valid HTML. Here's a test:

test("simple", () => {
  let actual = jsx("h1", { children: "Hello" });
  expect(actual).toBe(`<h1>Hello</h1>`);
});

Let's implement that as simply as we can to make the test pass:

function jsx(tag, props) {
  let { children } = props;
  return `<${tag}>${children}</${tag}>`;
}

export { jsx };

Void elements

That works great. However I've just remembered that some HTML tags are void elements. This means they don't use a closing tag because they cannot contain anything. For example <input>, not <input></input>. We should write a test to cover this:

test("void elements", () => {
  let actual = jsx("input");
  expect(actual).toBe(`<input>`);
});

Unfortunately there's no magic way to tell which elements are void; we'll have to check a list.

const VOIDS = new Set([
  "area",
  "base",
  "br",
  "col",
  "embed",
  "hr",
  "img",
  "input",
  "link",
  "meta",
  "source",
  "track",
  "wbr",
]);

function jsx(tag, props) {
  let { children = "" } = props;
  if (VOIDS.has(tag)) return `<${tag}>`;
  return `<${tag}>${children}</${tag}>`;
}

Sidenote: I originally had a big regexp here, but I performance tested it and the Set was 4 times faster ✨.

Multiple children

Cool, now we'll try a more complex example with multiple children:

<header>
  <h1>Hello</h1>
  <p>world</p>
</header>;
// ↓
jsxs("header", {
  children: [jsx("h1", { children: "Hello" }), jsx("p", { children: "world" })],
});

Looks like this passes the children as an array, and transpiles to a different function called jsxs, to allow implementations to handle this case separately. I think we can probably use the same function for both, and just alias the export.

Here's the new test:

test("array children", () => {
  let actual = jsxs("header", {
    children: [
      jsx("h1", { children: "Hello" }),
      jsx("p", { children: "world" }),
    ],
  });
  expect(actual).toBe(`<header><h1>Hello</h1><p>world</p></header>`);
});

We can make this pass by making sure we join any array children back to a string:

function jsx(tag, props) {
  // ...
  return `<${tag}>${join(children)}</${tag}>`;
}

function join(x) {
  return Array.isArray(x) ? x.join("") : x;
}

export { jsx, jsx as jsxs };

HTML attributes

Now what happens if our elements have attributes?

<h1 id="x">Hello</h1>;
// ↓
jsx("h1", { id: "x", children: "Hello" });

Here's a new test:

test("attributes", () => {
  let void = jsx("input", { id: "x", type: "text" });
  expect(void).toBe(`<input id="x" type="text">`);
  let kids = jsx("h1", { id: "x", foo: false, children: "Hello" });
  expect(kids).toBe(`<h1 id="x">Hello</h1>`);
});

We'll need to loop over the non-children props and turn them into key=value pairs, whilst filtering out any falsy/null/undefined values:

function jsx(tag, props) {
  let { children = "", ...rest } = props;
  let attrs = "";
  for (let [key, val] of Object.entries(props)) {
    if (v !== false && v != null) attrs += ` ${key}="${val}"`;
  }
  if (VOIDS.has(tag)) return `<${tag}${attrs}>`;
  return `<${tag}${attrs}>${join(children)}</${tag}>`;
}

HTML also has "boolean attributes". These are not key/value pairs, but instead are either just present or not present. This means any prop with a value of true should be set as just the key.

<h1 hidden>Hello</h1>;
// ↓
jsx("h1", { hidden: true, children: "Hello" });

We'll write a test:

test("boolean attributes", () => {
  let actual = jsx("h1", { hidden: true, foo: false, children: "Hello" });
  expect(actual).toBe(`<h1 hidden>Hello</h1>`);
});

We'll add a line into our attributes loop to handle this:

function jsx(tag: Type, props: Props) {
  // ...
  for (let [key, val] of Object.entries(rest)) {
    if (v === true) attrs += " " + key;
    // ...
  }
  // ...
}

Custom components

We've pretty much covered all regular HTML now. It would be great to handle custom components too, since that's what makes composing UIs with JSX feel so nice.

function Title({ children }) {
  return <h1>{children}</h1>;
}
<Title>Hello</Title>;
// ↓
function Title({ children }) {
  return jsx("h1", { children: "Hello" });
}
jsx(Title, { children: "Hello" });

We can see that rather than a string as the tag name we get passed the component function itself. We'll need to call this function and return the resulting HTML.

Here's a test:

test("component", () => {
  function Title({ children }) {
    return jsx("h1", { children: "Hello" });
  }
  let actual = jsx(Title, { children: "Hello" });
  expect(actual).toBe(`<h1>Hello</h1>`);
});

We can add a check to the start of our implementation to handle this:

function jsx(tag: Type, props: Props) {
  if (typeof tag === "function") return tag(props);
  // ...
}

Fragments

The final feature we're missing is "fragments". Since JSX transpiles to nested function calls it requires a single top-level element (unlike HTML). Fragments allow us to render multiple elements without a parent:

<>
  <div>hello</div>
  <div>world</div>
</>;
// ↓
jsxs(Fragment, {
  children: [
    jsx("div", { children: "hello" }),
    jsx("div", { children: "world" }),
  ],
});

Here we expect the fragment to render nothing in the HTML:

test("fragment", () => {
  let actual = jsxs(Fragment, {
    children: [
      jsx("h1", { children: "Hello" }),
      jsx("p", { children: "world" }),
    ],
  });
  expect(actual).toBe(`<h1>Hello</h1><p>world</p>`);
});

We need to create a separate export for this that just renders its children (which will either be a string or array of strings):

function Fragment(props) {
  return join(props.children);
}

export { jsx, jsx as jsxs, Fragment };

Wrapping up

That's it! Here's our entire JSX-to-HTML implementation in only 18 lines of code!

const VOIDS = new Set([ "area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "source", "track", "wbr"]);

function jsx(tag, props) {
  if (typeof tag === "function") return tag(props);
  let attrs = "";
  let { children = "", ...rest } = props;
  for (let [key, val] of Object.entries(rest)) {
    if (v === true) attrs += " " + key;
    else if (v !== false && v != null) attrs += ` ${key}="${val}"`;
  }
  if (VOIDS.has(tag)) return `<${tag}${attrs}>`;
  return `<${tag}${attrs}>${join(children)}</${tag}>`;
}

function Fragment(props) {
  return join(props.children);
}

export { jsx, jsx as jsxs, Fragment };

Update (May 2026): I have published an improved version of what we built in this post as Transclusion.

The lost art of progressive enhancement

Progressive enhancement is the idea that you should layer more powerful features on top of functional basics. For example starting with a regular HTML form, then adding JS to intercept submits and update the page selectively rather than doing a full browser navigation.

A long time ago this was a pretty standard practice, since it was the only way to build more complex web apps. However as the JavaScript language and DOM APIs improved, full client-side frameworks like Knockout.js (2010), Ember.js (2011) and React (2013) emerged that allowed devs to build an entire app client-side. This paradigm became known as a "Single-Page App" (SPA), since the server only had to provide a single HTML page—the first one. Everything after that was rendered client-side by assembling fetched data with client-side templates.

Unfortunately the rise of SPAs meant the death of progressive enhancement. Almost by definition you can't progressively enhance without server-rendering. There is no "minimum viable experience" before JS loads, parses and runs—just a blank white page that eventually (hopefully) gets populated with content.

Developers got used to just slapping a click handler on a button (since <button onClick={}> is so convenient in React), and collectively forgot that forms had helpful behaviour if you didn't e.preventDefault() them.

What's old is new again

Progressive enhancement is making a comeback as frameworks like Remix and SvelteKit provide simple APIs for interactivity where the easiest thing for devs to do is start with simple forms and links. For people not using JS metaframeworks as their backend the HTMX library has leapt into the spotlight.

HTMX

HTMX is a library for adding interactivity without writing your own JavaScript. It hooks into a set of declarative attributes in your HTML. These attributes coordinate behaviour like "fetch a fragment of HTML from this URL and insert it into this element". This is a surprisingly nice way to sprinkle enhancements into an app that is already functional the old-fashioned way.

Interestingly HTMX is not particularly focused on progressive enhancement. The docs encourage patterns that are entirely reliant on JS:

<button hx-post="/clicked" hx-swap="outerHTML">Click Me</button>

However it has a subset of features for enhancing links and forms that are perfect for enhancement: boosting. Adding hx-boost to links or forms opts in to a form of client-side routing (clicking/submitting will prevent the default behaviour and swap the new page into the <body>, avoiding a full page reload). Combining this with the hx-target attribute allows you to update specific subsets of the page following user interaction.

Building our own mini-HTMX

HTMX is kind of huge and complex, because it supports a ton of features I don't need (and IE11!). My favourite way to learn something properly is to rebuild a small part of it in a simpler way, so lets see how we could recreate the bits of HTMX we need.

We'll start with the basic counter from the previous article and work our way up to full progressive enhancement. Here's the form we want to enhance:

<form method="POST">
  <button name="diff" value="-1" aria-label="decrement">-</button>
  <output>{count}</output>
  <button name="diff" value="+1" aria-label="increment">+</button>
</form>

When the server receives the form's POST request it increments the count and redirects back to the same page. The browser reloads the entire page, which results in the new count showing in the <output>.

Note how the page refreshes after each click, resetting the timer and losing focus from the button.

Boosting forms

First we need to recreate exactly what the browser does when the form is submitted, only using our own JavaScript. The first step is to listen for form submissions and prevent the default behaviour if there's a data-boost attribute set on the element.

document.addEventListener("submit", async (event) => {
  let { boost } = event.target.dataset;
  if (boost !== undefined) {
    event.preventDefault();
  }
});

Since submit events bubble up we can just attach a single listener to the entire document to check all submissions. Any that aren't boosted will be ignored.

We now need to send a request to the server that matches what the browser would normally send. That means matching the action URL and method (we'll ignore enctype for simplicity). We'll write it as a separate function since this code is pretty self-contained:

function submit(event) {
  let { action, method } = event.target;
  let headers = { "content-type": "application/x-www-form-urlencoded" };
  let data = new FormData(event.target, event.submitter);
  let body = new URLSearchParams(data);
  return fetch(action, { method, headers, body });
}

Finally we need to actually send the request, then update the page by swapping the body with the response's body. We can turn the textual HTML response into a DOM using DOMParser, then extract the body:

// ...
event.preventDefault();
let res = await submit(event);
let body = await res.text();
let new_dom = new DOMParser().parseFromString(body, "text/html");
document.body.replaceChildren(...new_dom.body.childNodes);
// ...

Fantastic! We've written 18 lines of JS to achieve... the exact behaviour the browser already had (but with more bugs). However now that our code controls the process we can start to add enhancements.

Targeting

Currently page state is lost on reload—if a keyboard user had focused a button they'll have to tab their way back to it to continue incrementing the count

Ideally we want to surgically update just the bit of the page we know has changed, so the user doesn't lose their place and the app feels more "dynamic". Lets implement a simple version of HTMX's hx-target. It should let us specify a CSS selector for the element that should be updated, like this:

<form method="POST" data-boost data-target="output">

document.addEventListener("submit", async (event) => {
  let { boost, target } = event.target.dataset;
  if (boost !== undefined) {
    // ...
    let replacee = target ? document.querySelector(target) : document.body;
    replacee.replaceChildren(...new_dom.body.childNodes);
  }
});

Unfortunately this is now broken—we're replacing the content of the <output> with the entire body of the response. There are two ways to fix this.

Redundant responses

We don't need to send the entire new page when we receive a fetch request. Our server knows that the <output> will be updated in-place, and can send the minimal content required for the update.

HTMX sets custom headers like HX-Request and HX-Boosted so your server can customise its responses. However nowadays we can use the sec-fetch-dest header. The browser will set this to document for navigations from links or forms, and empty for fetch requests. So we can send different responses for the JS vs no-JS cases:

// ...
if (req.headers.get("sec-fetch-dest") === "empty") {
  return new Response(count, { headers: { "content-type": "text/html" } });
} else {
  return new Response("", { status: 303, headers: { location: "/" } });
}

The response is a bit of a hack here—we're sending invalid HTML (literally just a single digit), but browsers don't seem to care when parsing—the value of new_dom.body will be "1" (or whatever the count was).

Selecting

If you aren't willing (or are unable) to change your server response, HTMX supports extracting a subset of the HTML response using hx-select. Lets implement a simple version so we can grab the <output> from the response like this:

<form method="POST" data-boost data-target="output" data-select="output">

document.addEventListener("submit", async (event) => {
  let { boost, target, select } = event.target.dataset;
  if (boost !== undefined) {
    // ...
    let replacee = target ? document.querySelector(target) : document.body;
    let replacer = select ? new_dom.querySelector(select) : new_dom.body;
    replacee.replaceChildren(...replacer.childNodes);
  }
});

Either method here works—our client-side JS can now update just the parts of the DOM we need based on declarative attributes in the HTML. We don't even have to change anything about our server if we don't want to. This is a pretty powerful model!

Note how the timer keeps counting without interruption, and focus remains on the button.

Swapping

HTMX has a couple more features that make it possible to build even more dynamic UIs. Let's use the to-do list from the last post as an example. Here's the HTML:

<h1>Tasks</h1>
<form method="POST">
  <input name="task" aria-label="Your task" />
  <button aria-label="Add task">+</button>
</form>
<ol>
  <li>
    <span>Do the thing</span>
    <form method="POST" action="/remove" style="display: inline">
      <button name="id" value="1">&times;</button>
    </form>
  </li>
</ol>

When the first form is submitted the backend stores the new task in the DB, then redirects back to the same page but with the new task added to the start of the <ol> (so the most recent tasks are listed first).

We could enhance this form similarly to before. Our backend could return just the single new <li>, or we could use data-select to get just the first one from the full response:

<form
  method="POST"
  data-boost
  data-target="ol"
  data-select="li:first-child"
></form>

Since our implementation of data-select used document.querySelector we can use any valid CSS selector, allowing us to grab exactly the element we need using :first-child.

Unfortunately this won't quite work—we currently always replace all of the content of the target element with the selected element. So this code will remove all the existing todos.

HTMX has a way to control this: hx-swap. This lets you specify where in the target you want to put the new HTML. Our current implementation defaults to innerHTML—i.e. replace everything inside.

In this case we'd like to use what HTMX calls "afterbegin", which inserts the response before the first child of the target. Let's add support for this in our client-side code:

document.addEventListener("submit", async (event) => {
  let { boost, target, select, swap = "innerHTML" } = event.target.dataset;
  // ...
  if (swap === "afterbegin") replacee.prepend(replacer);
  if (swap === "innerHTML") replacee.replaceChildren(...replacer.childNodes);
});

And finally update our form:

<form
  method="POST"
  data-boost
  data-target="ol"
  data-select="li:first-child"
  data-swap="afterbegin"
></form>

Now our example should insert new tasks into the beginning of the list.

Targeting revisited

Our to-do list also supports deleting tasks. Each task has a form like this:

<li>
  <span>Do the thing</span>
  <form method="POST" action="/remove">
    <button name="id" value="1">&times;</button>
  </form>
</li>

The backend will receive POST requests to /remove, read the submitted id from the body, delete the corresponding task from the DB, then redirect back to the same page, which will re-render with the task removed.

We can't boost these forms right now because we have no way of deleting an element, and no way of easily targeting the parent <li> (without adding an ID to each one). Luckily HTMX supports both with hx-swap="delete" and hx-target="closest li". The first will ignore the response and just remove the element; the second allows us to target up the DOM tree from the form.

Let's add support for both to our client-side code:

document.addEventListener("submit", async (event) => {
  // ...
  let replacee = target.startsWith("closest")
    ? event.target.closest(target.replace("closest ", ""))
    : target
    ? document.querySelector(target)
    : document.body;
  // ...
  if (swap === "delete") replacee.remove();
});

And finally update our task forms:

<li>
  <span>Do the thing</span>
  <form
    method="POST"
    action="/remove"
    data-boost
    data-target="closest li"
    data-swap="delete"
  >
    <button name="id" value="1">&times;</button>
  </form>
</li>

Wrapping up

We've implemented a (very) small subset of HTMX in about 26 lines of JavaScript. This lets us enhance already functional server-side apps to make them feel more dynamic and improve their user-experience.

I think the HTMX model is a powerful alternative to both the old JQuery ad-hoc-DOM-manipulation model, and the new React duplicate-everything-client-side model. HTMX makes the server the source of truth, so you don't end up with the UI out of sync from the data. HTML attributes are just to control how HTMX reconciles server responses with the current UI.

I'm probably going to expand the code we wrote here into a tiny library to use on side projects that don't need a full framework.

It's worth noting that although I'm focusing on Bun here, Deno has most of these features (as does Cloudflare Workers, if you don't mind being locked into a platform). Also this competition has pushed Node to improve, so as of Node 18 it has a built-in test runner and support for fetch.

Hello world

Lets do a quick comparison between Node and Bun to render an HTML page. We'll use ES Modules since that's the modern standard (and Node supports it fine now). I'll try to write the most minimal version of each, just for fun.

Here's Node:

import { createServer } from "node:http";

let server = createServer((req, res) => res.end(`<h1>Hello</h1>`));
server.listen(3000, () => console.log(`Running http://localhost:3000`));

Here's Bun:

let server = Bun.serve({ fetch: (req) => new Response(`<h1>Hello</h1>`) });
console.log(`Running http://localhost:${server.port}`);

We can see that Bun uses modern web standards (like returning a JS Response object), rather than relying on APIs that only work in one specific runtime.

It's a good idea to define your application code separately from the server config (e.g. so you can test the app without starting the server), so from here on I'll be defining the app as a separate function without the Bun.serve() bit. All the following code will be executed like this:

import { app } from "./app.jsx";

let server = Bun.serve({ fetch: app });
console.log(`Running http://localhost:${server.port}`);

JSX is nice

Template literal strings are honestly pretty decent for throwing together HTML, but can get frustrating for non-trivial UIs that you want to break up into smaller components. Template literals require you to just chuck a bunch of function calls into your HTML, which sort of ruins my flow when my brain is in "HTML-mode".

function app(req) {
  return new Response(`
    <nav>
      <ul>
        <li>
          ${NavLink({ children: "Home", href: "/" })}
        </li>
        <li>
          ${NavLink({ children: "About", href: "/about" })}
        </li>
        <li>
          ${NavLink({ children: "Contact", href: "/contact" })}
        </li>
      </ul>
    </nav>
  `);
}

JSX makes this a lot cleaner, and in my experience encourages better structure for your UI code.

function app(req) {
  return new Response(
    (
      <nav>
        <ul>
          <li>
            <NavLink href="/">Home</NavLink>
          </li>
          <li>
            <NavLink href="/about">About</NavLink>
          </li>
          <li>
            <NavLink href="/contact">Contact</NavLink>
          </li>
        </ul>
      </nav>
    )
  );
}

JSX also allows you to benefit from the wonderful world of JS-tooling. Since your HTML is defined as JS functions it can be checked by a linter or type system, which helps you avoid mistakes or accessibility problems. Template literals are just opaque strings from the perspective of your tooling.

(I know you could use a traditional templating language like Handlebars or Mustache and probably some kind of separate HTML linter, but honestly now that I've tasted "just use JS for templating" I can't go back.)

Configuring JSX

To use JSX in Node you pretty much have to transpile your server code back to regular JS with something like Babel, ESBuild or SWC. There are libraries like @babel/node but they aren't great for production usage. This ends up being such a faff that I never bother.

Bun supports JSX syntax natively, however by default it expects you to be using React, converting JSX like <h1>Hello</h1> into React.createElement("h1", {}, "hello").

For simple server-side apps I prefer @kitajs/html. Rather than constructing your UI as objects that must be converted to strings when you send a response, this turns the JSX directly into a string, saving a step.

Update: I have written about building my own JSX renderer and published it as part of a library.

JSX conversion is configured either in the specific config file for the runtime (bunfig.toml), or in a tsconfig.json/jsconfig.json. We'll use the latter since we want to keep this project runtime agnostic.

{
  "compilerOptions": {
    "jsx": "react",
    "jsxFactory": "Html.createElement",
    "jsxFragmentFactory": "Html.Fragment"
  }
}

Now <h1>Hello</h1> will be converted to Html.createElement("h1", {}, "hello") (which returns an HTML string). We need to install the dependency with bun add @kitajs/html, then import Html wherever we use JSX.

import Html from "@kitajs/html";

export function app(req) {
  return new Response(<h1>Hello</h1>);
}

Counter app

Lets make something slightly more involved. The traditional example for client-side frameworks seems to be a basic counter, so lets make one of those server-side.

Basic routing

Our app needs at least two routes: the home page should show the counter UI, and all other requests should get a 404 for now.

import Html from "@kitajs/html";

export function app(req) {
  let { pathname } = new URL(req.url);
  switch (pathname) {
    case "/":
      return new Response("<!doctype html>" + <h1>Hello</h1>, {
        headers: { "content-type": "text/html; charset=utf-8" },
      });
    default:
      return new Response("<!doctype html>" + <h1>Not found</h1>, {
        status: 404,
        headers: { "content-type": "text/html; charset=utf-8" },
      });
  }
}

(we need the <!doctype html> in our response to avoid browsers rendering the page in quirks mode.)

There's a lot of boilerplate for rendering HTML responses being repeated, so lets extract a quick helper function:

import Html from "@kitajs/html";

export function app(req) {
  let { pathname } = new URL(req.url);
  switch (pathname) {
    case "/":
      return send(<h1>Hello</h1>);
    default:
      return send(<h1>Not found</h1>, 404);
  }
}

function send(body, status = 200) {
  return new Response("<!doctype html>" + body, {
    status,
    headers: { "content-type": "text/html; charset=utf-8" },
  });
}

Counter UI

Okay, now we can actually start building our app. Since this is entirely server-rendered we can't rely on client-side JS, which means we need to use <form>s for any interactivity. In the React world it's so easy to forget how much the browser can handle for us.

let count = 0;

export function app(req) {
  let { pathname } = new URL(req.url);
  switch (pathname) {
    case "/":
      return send(
        <form method="POST">
          <button name="diff" value="-1" aria-label="decrement">
            -
          </button>
          <output>{count}</output>
          <button name="diff" value="+1" aria-label="increment">
            +
          </button>
        </form>
      );
    // ...
  }
}

This form contains two different submit buttons. This means the form can send two different requests depending on which button is clicked. The decrement button will send a POST request to / with a body of diff=-1, whereas the increment button will send a body of diff=+1.

We'll just store the count in a variable for now. It will get reset whenever our server restarts, but that's fine for a demo. If we wanted it to persist we could store it in a cookie.

Count updates

Now we need to handle POST requests. The server should update the count variable by the amount specified in the request body, then redirect back to the home page so the user sees the updated UI.

let count = 0;

export async function app(req) {
  switch (req.url) {
    case "/":
      if (req.method === "GET") return send(/*...*/);
      if (req.method === "POST") {
        let body = await req.formData();
        let diff = body.get("diff");
        count += Number(diff ?? 0);
        return new Response("", {
          status: 303,
          headers: { location: "/" },
        });
      }
    // ...
  }
}

Note that we had to make app an async function, since the methods for parsing request bodies return promises. Note also that this is an entirely standardised and built-in way to extract the body—no middleware or external dependencies required.

We return a redirect using the exact same API as the other responses, just specifying the right status code and location header so the browser knows how to handle it.

And that's it! A robust server-rendered counter app in under 50 lines of JS(X). Let's see if we can do something a bit more complicated.

Tasks app

The next step for every framework demo after a counter is tasks. This will be a little more complex and stateful.

SQLite storage

We need somewhere to store tasks. We could just keep them in memory like the count in the previous example, but lets push ourselves to do something more robust. SQLite is a great database, and Bun just so happens to have a driver built in.

We'll create a database and execute some SQL to create a table for storing tasks:

import { Database } from "bun:sqlite";

const db = new Database("tasks.sqlite");
db.run(`
  create table if not exists tasks (
    id integer primary key autoincrement,
    task text not null,
    created text default current_timestamp
  )
`);

Running this will create a new file named tasks.sqlite in our working directory.

We can now write SQL statements to create, list and remove tasks:

function create(task) {
  return db.query(`insert into tasks (task) values (?)`).run(task);
}

function list() {
  return db.query(`select * from tasks order by created desc`).all();
}

function remove(id) {
  return db.query(`delete from tasks where id = ?`).run(id);
}

Tasks UI

Now lets put together a nice HTML form for adding new tasks. We'll stick to the rough routing structure from the counter example.

export async function app(req) {
  let { pathname } = new URL(req.url);
  switch (pathname) {
    case "/":
      if (req.method === "GET") {
        return send(
          <main>
            <h1>Tasks</h1>
            <form method="POST">
              <input name="task" aria-label="Your task" />
              <button aria-label="Add task">+</button>
            </form>
          </main>
        );
      }
      if (req.method === "POST") {
        // @todo
      }
    default:
      return send(<h1>Not found</h1>, 404);
  }
}

Task updates

Now we need to handle the form submission, read the POST body, then save the task to the DB:

export async function app(req) {
  // ...
  switch (pathname) {
    case "/":
      // ...
      if (req.method === "POST") {
        let body = await req.formData();
        let task = body.get("task");
        create(task);
        return new Response("", {
          status: 303,
          headers: { location: "/" },
        });
      }
    // ...
  }
}

We can now save tasks, but they don't show up in the UI. We need to read them from the DB, then render as a list:

export async function app(req) {
  // ...
  switch (pathname) {
    case "/":
      if (req.method === "GET") {
        let tasks = list();
        return send(
          <main>
            <h1>Tasks</h1>
            <form method="POST">
              <input name="task" aria-label="Your task" />
              <button aria-label="Add task">+</button>
            </form>
            <ol>
              {tasks.map((t) => (
                <li>{t.task}</li>
              ))}
            </ol>
          </main>
        );
      }
    // ...
  }
}

Task removal

Finally we need to add a delete button to each task. There are a couple of ways we could structure this:

1. Add a form with its own submit button to each list item
2. Add a single form around the entire list

I'm going to do the second, purely because it'll have a bit less repetition.

export async function app(req: Request) {
  // ...
  switch (pathname) {
    case "/":
      if (req.method === "GET") {
        let tasks = list();
        return send(
          <main>
            {/* ... */}
            <form method="POST" action="/remove">
              <ol>
                {tasks.map((t) => (
                  <li>
                    <span>{t.task}</span>
                    <button name="id" value={t.id} aria-label="Remove task">
                      &times;
                    </button>
                  </li>
                ))}
              </ol>
            </form>
          </main>
        );
      }
    // ...
  }
}

Clicking the delete button next to each task will send a POST request to /remove. The body will be id=1, with the value changing for each task depending on what button was clicked.

Finally we need to handle the POST request on the server. We should read the body, get the ID of the task to be deleted, then remove it from the DB and redirect back to the home page.

export async function app(req: Request) {
  // ...
  switch (pathname) {
    case "/":
      // ...
    case "/remove":
      if (req.method === "POST") {
        let body = await req.formData();
        let id = body.get("id");
        remove(id as string);
        return new Response("", {
          status: 303,
          headers: { location: "/" },
        });
      }
    // ...
  }
}

And that's it! A speedy server-rendered tasks app that persists information to a proper database in under 100 lines of JS(X).

A simpler world

I honestly love building apps like this. A fast, simple, batteries-included runtime plus SQLite can make quickly a breeze. You obviously lose out on dynamic client-side interactivity, so look out for my next post when we start progressively enhancing these forms.

This "arbitrary variant" lets you apply styles when this element is nested inside another element with this class. For example:

<ul class="[&_&]:pl-4">
  ...
</ul>

This list will only have padding-left applied if it inside another such list.

Why would you do this

I've been building a simple app for reading Reddit because the native UI is awful and they killed all the good 3rd party apps. Reddit comments are nested. That is, unlike other platforms like Twitter 𝕏, every comment can have multiple separate threads of replies nested within.

These nested comment trees are usually rendered with progressively more space on the left, so that its obvious which parent the comments belong to. Here's a visualisation:

Parent 1
├─ 1st reply to parent 1
└─ 2nd reply to parent 1
   └─ 1st reply to 2nd reply to parent 1
      └─ 1st reply to 1st reply to 2nd reply to parent 1
Parent 2
├─ 1st reply to parent 2
└─ 2nd reply to parent 2

Creating the nested UI

I found this UI was best expressed with a recursive component. Using JSX:

function Comments({ comments }) {
  if (comments.length === 1) {
    return null; // Reddit's API has a "More" object at the end of the tree
  }
  return (
    <ul className="List">
      {comments.map((child) => {
        return (
          <li key={child.id}>
            {/* Lots of comment markup removed for brevity*/}
            {child.replies && <Comments comments={child.replies} />}
          </li>
        );
      })}
    </ul>
  );
}

This component renders a list of comments, and inside of each comment (if there are replies) renders another copy of itself. Here's an example of the resulting markup:

<ul class="List">
  <li><p>A comment with no replies</p></li>
  <li>
    <p>A comment with one reply</p>
    <ul class="List">
      <li><p>First reply</p></li>
    </ul>
  </li>
</ul>

Styling with vanilla CSS

This works great for rendering the nested lists, but we still need to style them. Ideally nested comments have the correct border and spacing to make it obvious which parent they are replies to.

This isn't too hard with vanilla CSS:

.List .List {
  margin-top: 1rem;
  border-left: 1px solid;
  padding-left: 1.5rem;
}

CSS selectors work left-to-right. So the selector .List .List means "find all elements with the classname "List", then check if they're inside an element with the classname "List". This is exactly what our UI needs: top-level comments won't get any extra spacing or border, but all nested comments will.

The big refactor

Once I had a functioning prototype I decided to refactor the styling to use the Tailwind library. I had a vague justification that it was getting a little bit unwieldy just raw-dogging CSS, but really I was just bored. What else are side-projects for? I did also feel like I owed Tailwind a fair try since I've been pretty vocally critical of it in the past. I'm working on a full write-up of my thoughts, but here's a sneak preview: Tailwind is pretty good now!

Most of the styles were easy to port over to Tailwind's "just bung it all in the classname and never think about it again" approach. However a few CSS tricks like the nested comments had me stumped for a while.

Tailwind only lets us apply classes to an element directly. There are some special-cased things for parent/sibling relationships, but nothing for something nested within itself. I was tempted to just hack this with JS by passing down a prop indicating the nesting level of the recursion, but no way was I letting a utility-CSS library beat me.

After a little experimentation (and reading all the Tailwind release blog posts), I found the answer.

Arbitrary variants

This feature really needs a more exciting name, because it's really cool. Tailwind has supported arbitrary values since version 2.2. This is where you put any value you like in square brackets, and Tailwind just injects it into the generated CSS class. For example:

<p class="mt-[476px]">Hello</p>

That will generate this class in your CSS:

.mt-\[476px\] {
  margin-top: 476px;
}

This is great for one off things that don't fit into your wider design system.

However in version 3.1 Tailwind added arbitrary variants, and they're fantastic. Quick recap: variants are how you express things like hover states and media queries within a classname. For example:

<button class="hover:bg-red-100 xl:text-lg">Click me</button>

Arbitrary variants let you put anything you like as the modifier. You can basically put whatever regular CSS you want inside the square brackets to create your own variants on the fly. For example:

<p class="[&:nth-child(3):font-bold]">Hello</p>

This will make the text bold only if the element is the third child of its parent.

So the & (ampersand) character refers to the class itself, which is pretty mind-bending. This is a similar concept to how its used in CSS Nesting (and its inspirations in Sass/Less).

This means you can do fun stuff like:

<div class="[&>h2]:mt-4">...</div>

This will apply margin above any h2 elements within the div.

Bringing it all together

Now we have everything we need to adapt the nested list styles. We can use & as a reference to the current class (and therefore the element). This means we can use it twice to indicate the current class nested within the current class 🤯. Behold Gill, the inside-himself variant: [&_&].

<ul class="[&_&]:mt-4 [&_&]:border-l [&_&]:pl-5"></ul>

The underscore represents a space, as you can't use spaces inside variants (the pitfalls of writing all your styles inside a single attribute).

This generates the CSS we're looking for (with a lot of backslashes to escape the special characters):

.\[\&_\&\]\:mt-4 .\[\&_\&\]\:mt-4 {
  margin-top: 1rem;
}

.\[\&_\&\]\:border-l .\[\&_\&\]\:border-l {
  border-left-width: 1px;
}

.\[\&_\&\]\:pl-5 .\[\&_\&\]\:pl-5 {
  padding-left: 1.25rem;
}

I only needed a few rules in a single place, so I was fine leaving it like this. If you were going to need this variant again you could create a custom variant using a plugin in your Tailwind config:

const plugin = require("tailwindcss/plugin");

module.exports = {
  plugins: [
    plugin(function ({ addVariant }) {
      addVariant("inside-self", "&_&");
    }),
  ],
};

Using this would technically be more typing, but it's more explicit and saves characters compared to linking to this blog post in a comment every time you use [&_&].

Terminal problems

Most terminal emulators limit the number of lines you can scroll back (my iTerm2 appears to be set to 1000 lines). This is annoying when you are logging a lot—you literally cannot scroll back to view earlier logs.

You could bump up the limit, but unless you make it unlimited you'll hit this issue eventually. Also the limits are there for a reason—to stop your terminal sucking up all the memory with an ever-increasing scrollback buffer.

Terminals are not a particularly nice environment for browsing through logs, especially when you're logging structured data. They often don't support search, line-wrapping, syntax-highlighting etc. All of these are things you take for granted in a text editor.

Redirecting log output

Here's the fun trick: you can redirect the output of a program to a file with a single shell operator: >. You may have used this to quickly populate a file:

echo "hello world" > hello.txt

However this works just as well for the output of a Node program:

for (let i = 0; i <= 100; i++) {
  console.log(`The number is ${i}`);
}

$ node index.js > output.log

The number is 0
The number is 1
The number is 2
...

Capturing different types of log

Programs have three input/output connections: "stdin" (standard input), "stdout" (standard output), and "stderr" (standard error). Having two different outputs (one for normal logs and one for errors) can be helpful in cases where you want to only see one or the other.

By default the > operator only redirects stdout. This means that if our Node program logs an error using console.error (which outputs to "stderr") it will still show up in the terminal.

for (let i = 0; i <= 100; i++) {
  if (i === 23) console.error(new Error(`${i} is not allowed`));
  else console.log(`The number is ${i}`);
}

$ node index.js > output.log
Error: 23 is not allowed
    at Object.<anonymous> (/Users/oli/Code/node-pipe-logs/index.js:12:31)
    ...

We can also redirect stderr to a file by using 2>:

$ node index.js > output.log 2> errors.log

Error: 23 is not allowed
    at Object. (/Users/oli/Code/node-pipe-logs/index.js:12:31)
    ...

This is super helpful for debugging: if the errors file is empty you know everything worked fine; if not you have a nice list of everything that went wrong to peruse at your leisure.

I didn't want to spend much time on this, and I definitely didn't want to change my site's architecture or goals (fully static HTML/CSS with as little JS as humanly possible). Luckily the DuckDuckGo search engine made it super easy to add custom site search.

Summary

This article goes into a lot of detail about how I built this feature. If you just want the code you can see it on GitHub.

Long live the URL

Most search engines (including Google) take search queries as part of the URL. More specifically they extract them from the search parameters (the bit after a ?). For example if you search for css on google.com the browser sends a GET request to google.com/search?q=css&abunchoftrackingjunk (this is how form submissions work). The cool thing about this is that by default any form can submit to this URL (this is also how CSRF attacks happen unfortunately).

We can craft a form that submits a GET request to Google like this:

<form action="https://google.com">
  <label for="search">Search</label>
  <input name="q" id="search" />
</form>

If a visitor to my site enters "css" into this form they'll be sent off to Google to see the results, exactly as if they'd clicked a link to google.com?q=css.

This is great, but there were two big reasons I couldn't use Google in the end. The first is that I respect my visitors' privacy. Google does a lot of tracking that many people wish to avoid—I'm uncomfortable semi-tricking people into using a Google service. The second is that Google just wouldn't work.

Searching a single site

You may be aware that the only way to get decent results out of Google nowadays is to add site:reddit.com to your search. This relies on Google's ability to search a single site rather than the whole web.

This seemed perfect for my use-case. I could limit the results to site:oliverjam.com so visitors would only see my articles. Unfortunately as far as I can tell there's no way to configure this without adding it to the search query itself. I could have used JS to append it to the query on submit, but that goes against my "no JS unless absolutely necessary" goal.

This is when I discovered that DuckDuckGo has a way more robust set of search parameters for configuring results. They also use the q param for setting the query, but also support a sites param for specifying the domain to search.

Here's a form that searches this site on DuckDuckGo:

<form action="https://duckduckgo.com">
  <label for="search">Search</label>
  <input name="q" id="search" />
  <input type="hidden" name="sites" value="oliverjam.com" />
</form>

Customising the results page

It seems like DuckDuckGo actually want people to use this feature (shocking). They provide a plethora of parameters for making the search results page fit your brand better.

1. You can remove the branded DDG header from the top by setting k0=-2
2. You can remove all the adverts (!!!) by setting k1=-1
3. You can remove "related searches" with kz=-1
4. You can center the results with km=m
5. You can set a background colour with k7=#000

<form action="https://duckduckgo.com">
  <label for="search">Search</label>
  <input name="q" id="search" />
  <input type="hidden" name="sites" value="oliverjam.com" />
  <input type="hidden" name="ko" value="-2" />
  <input type="hidden" name="k1" value="-1" />
  <input type="hidden" name="kz" value="-1" />
  <input type="hidden" name="km" value="m" />
  <input type="hidden" name="k7" value="#fafef5" />
</form>

It honestly blew me away how far DuckDuckGo have gone in making this feature user-friendly.

Matching my site's theme

Although I could set a custom background colour, this wouldn't necessarily match my site. The param had to be hard-coded into the HTML for the form, which meant I had to pick either the light or dark background. It was quite a jarring experience going from dark-mode site to bright search results.

This was a scenario where I was willing to add a tiny bit of JS to improve the user-experience of this feature, since I couldn't think of any other way to have the value of a hidden input match the current document background.

I added a single line of JS to run when the form was submitted:

<form
  action="https://duckduckgo.com"
  onsubmit="this.k7.value = getComputedStyle(document.documentElement).backgroundColor"
></form>

This sets the value of the hidden input to whatever the <html> element's background currently is. Since it happens on submit it should always match the user's theme preference, even if this changed as they were searching.

Opening results in a new tab

I'm still on the fence about this feature. I generally dislike links that forcibly open in a new tab (sometimes I don't want this! let me choose!), but for search results on another domain entirely I felt like a new tab was a sensible choice.

This blew my mind when I learnt it—you can make a form submit to a new tab using the exact same attributes as a link. It makes sense when you think about how links and forms are both just ways to navigate.

<form action="https://duckduckgo.com" target="_blank" rel="noopener"></form>

Conclusion

I wrapped all this code up into a reusable component with comments so I wouldn't forget what the inscrutable search parameters did in the future (they came in handy writing this post). You can also see the source on GitHub.

/**
 * DuckDuckGo offers a lot of customisation via URL params
 * https://duckduckgo.com/params
 * ko=-2 Remove header
 * k1=-1 Remove adverts
 * kz=-1 Remove instant answers/related searches
 * km=m  Center results
 * k7=#  Set background colour
 */

export function Search() {
  return (
    <>
      <form
        class="Search"
        action="https://duckduckgo.com"
        target="_blank"
        rel="noopener"
        onsubmit="this.k7.value = getComputedStyle(document.documentElement).backgroundColor"
      >
        <input type="hidden" name="ko" value="-2" />
        <input type="hidden" name="k1" value="-1" />
        <input type="hidden" name="kz" value="-1" />
        <input type="hidden" name="km" value="m" />
        <input type="hidden" name="k7" value="#fafef5" />
        <input type="hidden" name="sites" value="oliverjam.com" />
        <div class="grid pile items-center">
          <input
            type="search"
            name="q"
            aria-label="Search via DuckDuckGo"
            placeholder="Search"
            class="SearchInput"
          />
          <Icon name="search" size="20" />
        </div>
      </form>
    </>
  );
}

I'll start with the solution, then talk about alternatives afterwards.

Building a sprite sheet

Historically a "sprite sheet" was a single file containing lots of images, often for use in videogames. Storing all the images in one file helped with performance on under-powered systems. To display a specific image the program would crop the coordinates for that part, hiding the rest of the file.

SVG has this capability built in via the <use> element. This takes a node from within an SVG and duplicates it for display. Usually this is used within the same SVG as the source node, but crucially it doesn't have to be.

You can use the href attribute to copy a node from any SVG, even one loaded as a separate file. For example:

<svg width="20" height="20">
  <use href="/icons.svg#circle" />
</svg>

This will load /icons.svg, then find the node with ID "circle" and duplicate that here. The other half of the puzzle is to ensure that file contains an SVG with each icon specified as a <symbol>.

<svg xmlns="http://www.w3.org/2000/svg">
  <symbol id="circle" viewBox="0 0 20 20">
    <circle cx="10" cy="10" r="10" />
  </symbol>
  <symbol id="square" viewBox="0 0 20 20">
    <rect width="20" height="20" />
  </symbol>
</svg>

The SVG file can contain as many icons as you like as long as you give each symbol a unique ID.

That's it! My process for adding a new icon is:

1. Find an SVG (usually on Heroicons)
2. Copy/paste it into my icons.svg file
3. Change the <svg> tag to <symbol> and add an ID

The advantage of this technique is that you can cache the sprite sheet so each visitor to your site only has to download it once. The downside is that they must download every icon even if the page they view only uses a single SVG. Unless you have a ton of icons I don't think this is a big deal (my entire sprite sheet is 2.67KB gzipped).

Alternatives

There are only really two viable ways to use SVGs:

1. Reference the SVG file with an image element (<img src="circle.svg">)
2. Put the SVG markup directly in your HTML (<svg><circle .../></svg>)

Storing each SVG as a separate file and just using image elements is relatively simple, but loses you one of the best benefits of SVGs: styling them with CSS. Icons usually want to inherit their colour from the surrounding text, which doesn't work with a self-contained image file. The colour is just whatever is hard-coded inside the file, and that's it.

Putting the SVG markup in your HTML works great. If you only need to use an icon once or twice I highly recommend just pasting it in there. However you will eventually feel the pain of duplication. Also larger icons look messy taking up a bunch of space in your HTML with all their random path data:

<article>
  <h2>Some nice neat HTML</h2>
  <p>
    Published at
    <svg id="clock" viewBox="0 0 24 24">
      <path
        d="M12 2.25c-5.385 0-9.75 4.365-9.75 9.75s4.365 9.75 9.75 9.75 9.75-4.365 9.75-9.75S17.385 2.25 12 2.25zM12.75 6a.75.75 0 00-1.5 0v6c0 .414.336.75.75.75h4.5a.75.75 0 000-1.5h-3.75V6z"
      />
    </svg>
  </p>
</article>

In this case you either need to use a sprite sheet as above, or a component system as below.

React components

If you're using a component/templating system (like React) you may have solved this duplication problem by making each icon a separate component. For example:

export default function CircleIcon() {
  return (
    <svg viewBox="0 0 20 20">
      <circle cx="10" cy="10" r="10" />
    </svg>
  );
}

Some framework/bundler setups even support importing SVG files directly (like Create React App does) to get a component.

There are downsides to this. First, JSX is different to HTML and so requires you to camelCase SVG attributes. This is annoying enough that Heroicons offers icons in either standard SVG or JSX format.

Second if you server-render and hydrate your HTML (as frameworks like Next.js and Remix do by default), you will end up with your icons duplicated in both the HTML page and your JavaScript bundle.

This is true of all your markup, not only the icons, as it's a currently unavoidable side-effect of hydration. It's just more annoying here since icons are almost always static markup with no interactivity. If there are no event handlers or state attached to the icon then there's no need for it to be embedded in your JS.

“Please don't import SVGs as JSX. It's the most expensive form of sprite sheet: costs a minimum of 3x more than other techniques, and hurts both runtime (rendering) performance and memory usage.

This bundle from a popular site is almost 50% SVG icons (250kb), and most are unused.”

Jason Miller (@_developit)

Best of both

If you're working with a component system you can build an abstraction for rendering the <use href=""> elements, but let the browser handle actually rendering the SVG. Here's the one I wrote for this site:

export function Icon({ size = "20", name, ...rest }) {
  return (
    <svg {...rest} width={size} height={size} aria-hidden="true">
      <use href={`/assets/icons.svg#${name}`} />
    </svg>
  );
}

Now I don't have to worry about typing out the width/height etc every time I use an icon, I can just do <Icon name="article" />.

I'm looking for something quick and easy to setup, that doesn't require my code to be written a certain way, and has a free tier. That last one has gotten harder to find (probably blame cryptocurrency shenanigans). It's important to me because most of my random side-projects average less than one user a month—paying a nominal $5 or something for that is pretty silly.

What is Fly?

Fly is a "Platform-as-a-service" provider (PaaS), sort of like Heroku. You give them your app's code and they provision the server to run it on.

They require a payment method even if you're staying within the free tier to prevent abuse, but limits are pretty generous. You get three shared-CPU 256MB RAM virtual machines to play with, and everything scales with usage beyond that. Each additional machine costs $1.94, which is a lot better than some services where crossing the threshold from "basic" to "pro" plan can triple your spend.

How do you deploy?

You have to install and use Fly's command-line tool to deploy, which is a bit annoying. It would be nice if they had an HTTP service or something (Heroku do). However it seems to be the norm nowadays to have a CLI client for every service you use.

The canonical way to deploy appears to be:

1. Install the Fly CLI
2. Authenticate the CLI with flyctl auth login
3. Detect config and deploy with flyctl launch

Fly does some magic to figure out how to build your code (e.g. "this is a Next.js app so it needs Node etc"), provisions a machine in the region of your choice, then builds and deploys your code. After you've run launch once you can re-deploy with flyctl deploy.

This process also generates a bunch of config and dumps it into your project, which is a little weird the first time. You'll end up with a fly.toml, Dockerfile and .dockerignore. Although Fly magically figures out how your app works it insists on writing it down for next time. This is sort of nice as you can see the assumptions it made and tweak them if you need to.

fly.toml

The fly.toml file is how you configure the machine your app runs on. I think this is about as minimal as you can go:

app = "next-cookie-session"

[[services]]
  internal_port = 8080

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

Your app needs a name and at least one "service". Services have internal ports they listen on and can have outside internet traffic routed to them. In this case we're having Fly forward all HTTPS traffic from port 443 to our app on port 8080.

You can add a lot more config in here to control how your machine restarts or handles errors, health check requests, load balancing and concurrency etc.

Dockerfile

It's a bit weird to have a Dockerfile generated when you weren't planning on using Docker. Fly uses these as a universal "describe what your app needs" language. Here's a minimal Dockerfile for a Node.js app:

FROM node:16-alpine
WORKDIR /app
COPY . .
CMD ["npm", "start"]

This effectively tells Fly: "I'm going to need a machine with Node version 16 installed, copy my files into the /app directory, then run npm start to get the server going". But this could just as easily describe something different, like a Go app.

It's important to note that you don't have to use Docker yourself—if you don't have Docker installed Fly will provision a free "builder" machine in your account, and use that to build all your apps in the cloud.

Persistent volumes

Almost all PaaS services nowadays are "ephemeral". This means they recreate your app from scratch every time you deploy (and sometimes more often), because it's simpler to treat the Git repo as the source of truth.

Unfortunately this means you cannot rely on anything in the machine's filesystem sticking around. This makes it hard to use a simple database like SQLite, since that relies on writing files.

Fantastically Fly avoids this problem with their Volumes feature. This lets you specify a chunk of storage on the machine that should be kept around permanently.

You create a volume using the CLI:

flyctl volumes create myapp_data --region lhr --size 1

This will create a 1GB volume for the app whose fly.toml is in the current directory. You can use this volume in your app by adding it to the fly.toml:

[mounts]
  source="myapp_data"
  destination="/data"

This maps the volume to the /data directory in your app. You would then configure your database to store files in here.

Frustrations

Coming from Heroku I would like a slightly simpler experience for beginners or devs deploying very simple apps. Maybe Heroku is too magical, but I kind of miss not really needing any configuration at all to get started.

You can use Heroku-like buildpacks rather than Dockerfiles, but I found the docs on this a bit confusing (and lacking examples). It seems like Fly have been moving pretty quickly and iterating on this stuff, so example config in the wild often doesn't match up. My experiment with a buildpack didn't end well (deploying was way slower than with a Dockerfile, and it broke a lot).

The default fly.toml and Dockerfile have a lot in them, and this could be offputting or confusing to beginners. I had a frustrating time trying to figure out exactly what was required and what was a nice-to-have.

It turned out quite a lot of both files could be deleted without breaking my app. The docs are partly to blame here—the section on fly.toml don't really specify what default values it uses, or what config is absolutely necessary.

Conclusion

I'm a fullstack dev who mostly writes JS, with a bias towards UX/UI. I don't want to spend a lot of time or energy dealing with low-level primitives—I just want to make apps. I've gone through so much frustration in the past dealing with the complexities of AWS, so it's incredibly heartening to see a new player in this space focused on a better experience for devs like me.

I'll probably be putting anything I need a server for on Fly for the foreseeable future.

The browser and Node might share the JavaScript language, but they are very different environments. This means it can be awkward to wrangle things when you have some code written for the browser (accessing browser APIs like document.querySelector), but you want to execute that code in a more convenient Node environment (e.g. to run some tests in your terminal).

You cannot simply import browser-JS into Node, since it will rely on a bunch of missing global variables like document or window. If you want to write anything but a simple unit test you will probably need the accompanying HTML too—the elements the JS manipulates.

Testing in the browser

You can get around this problem by sacrificing some convenience and running your tests in the browser. This means including your test files as <script> tags in your HTML, and using the browser console as the place to view test results. The QUnit testing library can be used this way.

This isn't ideal though, since your tests aren't really automated anymore. You have to manually open the HTML file in a browser, then open the console to view the results. This precludes for example running the tests as part of a continuous integration pipeline to automatically catch any bugs you've introduced.

Testing in Node

The jsdom Node library is a huge, complex piece of magic. It effectively reimplements swathes of the browser APIs purely in Node. This means we can give it some browser-code, have it run that code, then query the resulting document from inside Node without ever involving a real browser.

There are of course some complications to setting this up, which I have documented here. Let's try and write a test for a simple DOM app that converts a string to uppercase. Here's the brief source code:

<form>
  <label>
    Text to uppercase
    <input name="input" />
  </label>
  <button>Convert</button>
  <output name="output"></output>
</form>
<script>
  console.log("hello from the browser");
</script>
<script src="index.js"></script>

let form = document.querySelector("form");
form.addEventListener("submit", (event) => {
  event.preventDefault();
  let input = event.target.elements.input.value;
  let output = event.target.elements.output;
  output.textContent = input.value.toUpperCase();
});

The code examples will assume you're using Node 18 and writing ES Modules rather than CommonJS (i.e. using import/export, not require).

Loading an HTML file

jsdom's primary API is to load a string of JS. In our case we would like to load an HTML file, since that's how our app is structured. Luckily jsdom provides a method for this:

import { JSDOM } from "jsdom";

let dom = await JSDOM.fromFile("index.html");
console.log(dom.window.document);