SSR & Production

PikaCSS output is a static CSS file produced at build time. That single fact answers most SSR and production questions.

SSR, SSG, and Streaming Just Work

There is no runtime style injection and no style registry to flush:

• Every pika() call is replaced during the build with the owning entry's configured class-name output (a string by default, or a string array with transformedFormat: 'array'). No PikaCSS styling function remains for the server or browser to execute.
• Each project entry owns a logical cssModule and corresponding runtime CSS artifact; the default single-entry specifier is pika.css. Your bundler handles whichever logical CSS modules you import like ordinary stylesheet imports.

So server-side rendering, static site generation, and streaming responses need no PikaCSS-specific handling: if your setup can serve a regular imported stylesheet, it can serve PikaCSS. There is no extractCriticalToChunks, no ServerStyleSheet, no hydration mismatch surface from styling.

For Nuxt specifically, single-entry authoring gets a generated plugin template that imports its sole cssModule. Explicit multi-entry authoring does not guess a global stylesheet; import the intended CSS modules explicitly. See Nuxt.

Production Builds

In build mode, Integration builds a complete usage snapshot from each entry’s canonical project-config scan rules and publishes the corresponding runtime CSS through a project-level transaction. Each entry output can contain:

• the @layer order declaration,
• preflights (with unused variables and keyframes pruned),
• the deduplicated atomic classes — sized by unique declarations, not call sites (see How PikaCSS Generates CSS).

The result passes through your bundler's normal CSS pipeline (minification, hashing, code splitting) untouched by PikaCSS.

What Triggers a Reload in Dev

Source edits and generation-input edits intentionally take different paths:

The dev server re-derives and atomically replaces the project generation when:

• The config file changes. The resolved pika.config.* file is watched. Only a content change counts — saving without editing anything, or a change that leaves the bytes identical, is ignored.
• A finalized config dependency changes. Plugins that load external files register their file/existence dependencies during Engine initialization through configureEngine (for example, @pikacss/plugin-design-tokens registers token source files). Integration combines those finalized Engine dependencies with Config-host dependencies into the project-generation watch set, and supported hosts re-derive the generation when one changes. Dependency registration is initialization-only: runtime/source transforms cannot add a newly discovered path to an already finalized Engine or dynamically expand the active watcher.

Both paths rely on the file-watching lifecycle of an officially supported host. Ordinary source edits do not re-create the engine; they only add or update the affected file's usages, and the generated CSS is rewritten only when the resolved styles actually changed. pika.gen.ts is never regenerated by source edits at all: the generated declarations are a deterministic projection of the effective engine/type configuration, so they refresh only when a genuine type-surface input changes (config reload, plugin-contributed autocomplete, and similar).

Re-deriving the project generation triggers a full page reload, not an HMR update (Vite). Atomic class names are assigned in discovery order, so a fresh engine can hand the same name to a different declaration. Anything the browser still holds from the previous generation would then point at the wrong rule — silently, with no error — so the page is reloaded to keep the served modules and the regenerated CSS in the same generation. Expect to lose page state (form input, router position) when you edit your config.

A config file that fails to evaluate is the exception: the dev server keeps the last-good engine, so nothing is reassigned and the page is left alone. Fix the file and save again to pick it up.

Type-Level Performance

The size of the generated pika.gen.ts (autocomplete unions) grows with your project. TypeScript type-system cost is tracked with an in-repo benchmark suite (scripts/type-bench/) that measures check time, instantiations, and IDE latency across usage scales and TS versions — so regressions in type performance are measured, not guessed. No absolute numbers are published because they depend heavily on project shape and hardware.

Next

• How PikaCSS Generates CSS — the runtime model behind the output file.
• Unplugin — supported bundler adapters, bootstrap selectors, and production lifecycle.
• Nuxt — the Nuxt module's auto-wiring.