Server rendering
The server renders your app to HTML with React DOM. A style registry collects the CSS of that render, and you write it into <head>. The browser then hydrates the same app.
On the server
Render the whole document with React, not only the app:
import { renderToString } from 'react-dom/server'
import { createStyleRegistry, StyleRegistryProvider, styleTagsHTML } from '@rootnative/web/server'
import { App } from './App'
export function renderPage(): string {
const registry = createStyleRegistry()
const html = renderToString(
<html lang="en">
<head>
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
<div id="root">
<StyleRegistryProvider registry={registry}>
<App />
</StyleRegistryProvider>
</div>
<script type="module" src="/client.js" />
</body>
</html>,
)
return `<!doctype html>${html.replace('</head>', `${styleTagsHTML(registry)}</head>`)}`
}
The script path depends on your bundler. Put the root CSS from Installation in the head too.
Three rules:
- One registry per request. A shared registry mixes the CSS of two requests.
- Write the style tags after the render ends. The registry fills while React renders. A head that you send before the body renders misses the CSS of that body.
- Render the
<head>with React. React 19 puts the<title>and<meta>elements ofHeadinto the<head>that it renders. If you render only the app and paste it into a template, they land at the start of<body>.
Your server code needs the same setup, so that App and its imports resolve to @rootnative/web. With Vite's server rendering, the Vite plugin does it.
renderStyleTags(registry) returns the same three <style> elements as React elements. Use it when your framework takes head elements, not a string.
In the browser
Hydrate the same app into the same element:
import { hydrateRoot } from 'react-dom/client'
import { App } from './App'
hydrateRoot(document.getElementById('root')!, <App />)
The client needs no provider. It finds the three <style> elements by their id and adopts their rules, so it inserts no rule twice. Keep them in their order: the defaults of the components, then the shorthands, then the longhands.
Values that differ on the server
The server doesn't know the window or the user's settings. Two hooks return a fixed value on the server and during hydration, so the first client render matches the server HTML. The real value arrives right after hydration.
| Hook | On the server and during hydration |
|---|---|
useWindowDimensions() | { width: 0, height: 0, scale: 1, fontScale: 1 } |
useColorScheme() | 'light' |
In render, use these hooks, not Dimensions.get() or Appearance.getColorScheme(). The two getters return the fixed value on the server but the real value in the browser at once, so a render that reads them doesn't match the server HTML.
A layout that depends on the window width renders its zero-width branch first. Use flex and percentages for the first paint, and refine after hydration.