# Server-Side Rendering (SSR)
Render typestyles on the server for better performance and SEO
TypeStyles supports SSR out of the box. Instead of injecting styles into the DOM during rendering, you can collect all the CSS on the server and include it in the HTML response.
## Request-safe collection
Every `collectStyles()` call runs inside an **isolated sheet store**. On Node, that isolation uses `AsyncLocalStorage`, so concurrent SSR requests (multiple Express handlers, parallel Remix bots, overlapping `renderToString` passes) each get their own CSS buffer. CSS from request A never leaks into request B.
This matters for:
- **Concurrent HTTP handlers** — two users hitting your server at the same time
- **The two-pass streaming pattern** — a sync `renderToString` pass for CSS, then `renderToPipeableStream` for the response (see below)
- **Async renders** — `collectStyles(async () => …)` is supported; isolation holds for the full await
`collectStylesFromModules()` (build extraction) uses the same isolation. In the browser bundle, isolation is a no-op because there is only one document.
## Basic setup
Import `collectStyles` from `typestyles/server`:
```ts
import { collectStyles } from 'typestyles/server';
import { renderToString } from 'react-dom/server';
const { html, css } = collectStyles(() => renderToString());
```
The `collectStyles` function:
1. Starts collecting CSS instead of injecting it
2. Runs your render function
3. Returns the rendered HTML and collected CSS
## Full example
Here's a complete Express.js example:
```ts
import express from 'express';
import { collectStyles } from 'typestyles/server';
import { renderToString } from 'react-dom/server';
import { App } from './App';
const app = express();
app.get('/', (req, res) => {
const { html, css } = collectStyles(() => renderToString());
res.send(`
My App
${html}
`);
});
app.listen(3000);
```
## How it works
During SSR:
1. **Collection mode**: When `collectStyles()` wraps your render, TypeStyles switches to collection mode
2. **CSS capture**: All styles, tokens, themes, and keyframes are captured to a buffer instead of being injected into the DOM
3. **Single style tag**: The collected CSS is returned as a single string ready to embed in your HTML
On the client:
1. **Hydration detection**: TypeStyles looks for an existing ``
- `streamingDocumentShell(css)` — doctype + `` with charset and styles + ``
- `injectStylesIntoHtml(html, css)` — insert before `` (Remix-style full documents)
- `TYPESTYLES_STYLE_ID` — the stable `"typestyles"` id (must match client hydration)
```tsx
import { renderToString, renderToPipeableStream } from 'react-dom/server';
import type { Response } from 'express';
import { collectStyles, streamingDocumentShell } from 'typestyles/server';
app.get('/', (req, res: Response) => {
const { css } = collectStyles(() => renderToString());
const { pipe } = renderToPipeableStream(, {
onShellReady() {
res.statusCode = 200;
res.setHeader('Content-Type', 'text/html; charset=utf-8');
res.write(streamingDocumentShell(css));
pipe(res);
},
onShellError(error) {
res.statusCode = 500;
console.error(error);
res.end();
},
});
});
```
If your shell opens wrappers around ``, add the matching closing tags in the appropriate callback (`onAllReady` when streaming deferred content, or follow the full pattern in the React docs) so you never write to `res` after it has ended.
**Next.js App Router** already streams — prefer `TypestylesStylesheet` or build-time extraction instead of manual two-pass rendering.
## Important considerations
### Style deduplication
TypeStyles automatically deduplicates CSS during collection. If multiple components use the same style variant, it's only included once in the output.
### Critical CSS
By default, `getRegisteredCss()` returns every rule registered in the process. For large apps, prefer **build-time per-route CSS** on Next.js: `buildTypestylesForNext` writes route-scoped stylesheets and a v2 manifest (see [zero-runtime — Next.js](/docs/zero-runtime#nextjs) and [per-route critical CSS](#per-route-critical-css-nextjs) below).
### Per-route critical CSS (Next.js)
`buildTypestylesForNext` traces each App Router `page` plus its layout chain, extracts CSS for modules that import `typestyles`, and writes self-contained files under `app/_typestyles/routes/` (default). The manifest maps route paths to those files:
```json
{
"version": 2,
"css": "app/typestyles.css",
"routes": {
"/": { "css": "app/_typestyles/routes/index.css" },
"/about": { "css": "app/_typestyles/routes/about.css" }
}
}
```
At request time, read the pre-built CSS for the current route instead of the full global sheet:
```tsx
// app/about/layout.tsx (Server Component)
import { getRouteCss } from '@typestyles/next/server';
export default function AboutLayout({ children }: { children: React.ReactNode }) {
const css = getRouteCss('/about', { root: process.cwd() });
return (
<>
{children}
);
}
```
Keep your convention entry minimal (tokens, reset, fonts). Route-specific `styles.*` modules imported only from that page's tree stay out of other routes' CSS files. Pass `routeCss: false` to `buildTypestylesForNext` when you only want the monolithic `typestyles.css`.
### Client-side hydration
Always use the same `id="typestyles"` on both server and client. Import `TYPESTYLES_STYLE_ID` from `typestyles/server` or use `typestylesStyleHtml()` so the id stays consistent:
```html
```
If the IDs don't match, you'll get duplicate styles.
### Memory and cleanup
`collectStyles()` manages collection state automatically. After the render function completes and CSS is collected, the internal state is reset. You don't need to manually clean up.
## Troubleshooting
### Styles missing in SSR output
Make sure you're actually rendering components that use typestyles during the `collectStyles()` call. If styles are defined but the component isn't rendered, no CSS will be generated.
### Styles appearing twice
This happens when the client can't find the server-rendered style tag:
1. Check that the `id` is exactly `"typestyles"`
2. Make sure the style tag is present in the initial HTML
3. Verify no ad blockers or CSP are interfering
### Flash of unstyled content (FOUC)
If you see FOUC:
1. Ensure styles are in the ``, not the body
2. Check that the CSS string isn't empty
3. Verify that `collectStyles()` wraps the actual component render, not just an empty render
Source: https://typestyles.dev/docs/ssr