Skip to content

Prerendering and hydration

An Underglass application can be rendered to HTML ahead of time, on a server or in a build, and hydrated in the browser. The page then shows its content before any script runs, search engines and other readers get real HTML, and the elements the server sent are the application’s original elements: React attaches to them, and GPU presentation later draws those same elements.

This is for the React adapter. Hydration needs nothing an ordinary mount does not need, and GPU presentation stays a separate, later step (enable()).

Render the same tree you mount in the browser with prerenderCanvasApp. You pass React’s own renderer, so @underglass/react never imports react-dom/server:

import { renderToString } from "react-dom/server";
import { prerenderCanvasApp } from "@underglass/react";
import { App } from "./App";
const html = prerenderCanvasApp(<App />, renderToString);

The result is the HTML of the three adapter-owned hosts (the hidden output canvas, the ordinary host and the overlay host) with your application inside the ordinary host. Write it as the only content of the sized, positioned frame element:

<div id="stage" style="position: relative; width: 800px; height: 480px"><!-- html goes here --></div>

It runs without a DOM: Node, a build plugin or an edge worker all do.

In the browser, createCanvasHosts finds the prerendered hosts in the frame and returns them instead of creating new ones. Mount the same tree with hydrate:

import { createCanvasHosts, mountCanvasApp } from "@underglass/react";
import { App } from "./App";
const hosts = createCanvasHosts(document.querySelector<HTMLElement>("#stage")!);
const gpu = mountCanvasApp({ ...hosts, hydrate: true }, <App />);
await gpu.enable(); // as usual, when you want GPU presentation

Hydration finishes before mountCanvasApp returns, as a client render does: the layers are registered and the controller is ready.

To see what React could not hydrate, pass your own hydrateRoot:

import { hydrateRoot } from "react-dom/client";
mountCanvasApp({ ...hosts, hydrate: true,
hydrateRoot: (container, tree) => hydrateRoot(container, tree, { onRecoverableError: console.warn }),
}, <App />);
  • Render the same thing on both sides. If the client’s first render differs from the HTML, React reports it and renders the tree again on the client. The application still works and can still enable GPU, but the prerendered elements are replaced. Keep browser-only values (window, localStorage, the current time) out of the first render: read them in an effect.
  • The controller is not there while prerendering. Components and hooks render as usual, but calling a controller method during render (useGPUHost().state(), for example) throws and names the method, and so does useNativeOverlayHost(). Use them from an effect or an event handler, where they only run in the browser.
  • A first render that throws makes the mount throw. React has discarded the prerendered markup by then, so catch the error from mountCanvasApp and show something. The same holds for a client render without hydrate. (With your own hydrateRoot or createRoot, React 19 reports the error to you instead: pass onUncaughtError.)
  • NativeOverlay has no prerendered markup. A portal cannot be hydrated, so an overlay renders nothing in the HTML and mounts right after hydration.
  • Colours are checked in the browser. appearance colours are validated with the browser’s CSS parser. While prerendering there is none, so a value is only refused when it holds something no colour does (a URL, an image, a second declaration, an unclosed bracket). The browser checks it fully when the page hydrates, and a value it refuses throws there, as in an ordinary mount.
  • inert is applied when the page hydrates. A Surface with inert or decorative is not inert in the HTML itself.
  • hydrate needs the prerendered hosts, and only them. Hydrating hosts that were created empty is refused, and so is an ordinary mount into prerendered hosts. The frame must hold no element or text but the three hosts (whitespace and comments around them are fine). Do not reformat the application’s markup inside them.
  • Layout comes from your CSS. Surface layout and appearance are inline styles, so they are in the HTML. Classes you use need their stylesheet loaded in the page’s <head>, or the content jumps when it arrives. A Content Security Policy that forbids inline styles blocks the hosts’ and the surfaces’ styles until the script runs.
  • Streaming (renderToPipeableStream), Suspense boundaries that hydrate later, and React Server Components. Only a complete renderToString render is tested.
  • Frameworks that own the React root themselves (Next.js, Remix): mountCanvasApp creates and owns its root.
  • The Vue adapter and the experimental worker backend.
  • React 18: the browser tests run on React 19 only. React 18 also logs its “useLayoutEffect does nothing on the server” warning while prerendering.
  • Browsers other than Chrome: nothing here is specific to it, but only Chrome is tested.

A plain-DOM application can use the same two core pieces, canvasHostsMarkup(content) and hydrate: true on mountApplicationModule: its mount then receives the prerendered container instead of an empty one.