Skip to the content

Server-Side Rendering

Apollion renders on the server without hydration mismatches and can produce static HTML that needs no client React. Class names are deterministic, styles are collected with styled-components' ServerStyleSheet, and the dark-mode flip is pure CSS.
Guides

The rule

  • Collect styles with ServerStyleSheet around the tree that contains ApollionProvider.
  • Hydrating apps use renderToString; static output uses renderToStaticMarkup.
  • Pass initialMode so 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
Scrolls sideways inside the table. The page does not.

Pitfalls

  • Rendering without initialMode while the client stores dark → the first client render differs from the server; pass initialMode from the same cookie.
  • Forgetting sheet.seal() after an error → keep it in finally.
  • Shipping the runtime theme object to a page with no React → link the tokens CSS instead.

See also