Server-Side Rendering
ServerStyleSheet, and the dark-mode flip is pure CSS.The rule
- Collect styles with
ServerStyleSheetaround the tree that containsApollionProvider. - Hydrating apps use
renderToString; static output usesrenderToStaticMarkup. - Pass
initialModeso the server and the first client render agree on the mode. - For markup with no React at all, link the CSS variables built by
@apollion-dsi/tokens.
How it works
Deterministic class names. The published build bakes a deterministic componentId into every styled
component and omits display names, so server and client agree on class names regardless of chunk order,
and shipped classes stay short (sc-<hash>-<index>).
import type { ReactElement } from 'react';
import { renderToStaticMarkup } from 'react-dom/server';
import { ServerStyleSheet } from 'styled-components';
import { ApollionProvider } from '@apollion-dsi/core/themes';
export function renderPage(app: ReactElement): string {
const sheet = new ServerStyleSheet();
try {
const body = renderToStaticMarkup(sheet.collectStyles(<ApollionProvider>{app}</ApollionProvider>));
return `<!DOCTYPE html><html><head>${sheet.getStyleTags()}</head><body>${body}</body></html>`;
} finally {
sheet.seal();
}
}For hydrating apps, use renderToString and inject sheet.getStyleElement() into the document.
Per-request theming. createTheme is pure and synchronous, so brand and mode can come from the
request: read the stored preference with readModeFromCookie and render the pre-paint script with it.
import { ApollionModeScript, readModeFromCookie } from '@apollion-dsi/core/themes/mode';
const preference = readModeFromCookie(request.headers.cookie) ?? 'system';
const initialMode = preference === 'dark' ? 'dark' : 'light';
// <ApollionModeScript persist="cookie" defaultMode="system" /> in <head>, then:
// <ApollionProvider colors={tenantSeeds} defaultMode={preference} initialMode={initialMode} persist="cookie">The full mode contract, including Next.js layouts, is on Dark Mode.
Interactive without client React. <Sheet static id> renders a native modal <dialog>: triggers
use getSheetTriggerProps() and one <SheetScript /> per page covers browsers without Invoker Commands.
Accordion is native <details>/<summary> and needs no script.
Static tokens. apollion-tokens build emits every variant as CSS custom properties, byte-identical
across runs and fingerprinted in manifest.json. Cache your static pipeline on its configHash.
Scenario | Use |
|---|---|
Next.js or another hydrating SSR | ServerStyleSheet + renderToString + ApollionProvider |
Static HTML, reports, e-mail | ServerStyleSheet + renderToStaticMarkup |
Dark mode in static output | output.cssModes stylesheet + getModeScript() |
Dialog or expand in static output | <Sheet static id> + SheetScript; Accordion |
Markup without React | CSS variables from apollion-tokens build |
Pitfalls
- Rendering without
initialModewhile the client storesdark→ the first client render differs from the server; passinitialModefrom the same cookie. - Forgetting
sheet.seal()after an error → keep it infinally. - Shipping the runtime theme object to a page with no React → link the tokens CSS instead.