How to properly handle CSS modules for SSR #20903

sbhehe233 · 2025-10-07T07:29:46Z

sbhehe233
Oct 7, 2025

Currently we are bundling the modules into one stylesheet and hardwire its URL in the HTML outputs, which feels a bit hacky as the emits would not be hashed. Would would be the standard/proper approach?

const ssrBuildConfig: BuildEnvironmentOptions = {
  ssr: true,
  outDir: "dist/server",
  ssrEmitAssets: true,
  copyPublicDir: false,
  emptyOutDir: true,
  cssCodeSplit: false, // suppress code splitting for css
  rollupOptions: {
    input: resolve(__dirname, "src/entry-server.tsx"),
    output: {
      entryFileNames: "[name].js",
      chunkFileNames: "[name]-[hash].js",
      assetFileNames: "[name][extname]", //  emit one `style.css`
    },
  },
};

// …
plugins: [
      tanstackRouter({
        target: "react",
        autoCodeSplitting: true,
        verboseFileRoutes: false,
      }),
      react(),
    ],
build: ssrBuildConfig
// …

// entry-server.tsx 
renderRouterToStream({
      request,
      responseHeaders,
      router,
      children: (
        <html lang="en">
          <head>
            {head || ""}
            <link rel="stylesheet" href="style.css" />
            <script
              type="module"
              src={
                import.meta.env.PROD
                  ? "/static/entry-client.js"
                  : "/src/entry-client.tsx"
              }
            ></script>
            <script>
              
            </script>
          </head>
          <body>
                <ServerRouter router={router} />
          </body>
        </html>
      ),

// _root.tsx 
import styles from "./root.module.scss";

  
              <Link
                to="/"
                activeProps={{
                  className: "font-bold",
                }}
                className={styles.menuItem}
              >
                <Home /> Home
              </Link>

official-burak · 2026-08-20T06:29:06Z

official-burak
Aug 20, 2026

Collect CSS from the client build manifest, not from the SSR Rollup output.

ssrEmitAssets plus cssCodeSplit: false writes an unhashed style.css from the server graph. That graph is not what the browser runs, so you lose content hashes and you can miss client-only CSS. Vite's backend-integration guide has the client build own hashed assets (build.manifest: true), then the HTML injects <link> tags from that manifest.

Leave cssCodeSplit on for the client build. In entry-server, read dist/client/.vite/manifest.json, take the client entry's css list, then walk imports and emit those CSS files too. Dev should keep middleware mode so Vite injects CSS itself. Drop the hardcoded href="style.css".

0 replies

Labeeb2339 · 2026-08-27T05:36:12Z

Labeeb2339
Aug 27, 2026

One extra detail in your config is the assetFileNames: "[name][extname]" override: it explicitly removes content hashes, so even a correct manifest will point at an unhashed stylesheet. Remove that override for the production client build and keep cssCodeSplit: true.

A typical SSR setup uses separate client and server builds. Enable build.manifest: true on the client build, then have the server read .vite/manifest.json, emit the entry chunk's css files, and recursively emit the css lists of its imports. Keep ssrEmitAssets on the SSR build only; it does not make the SSR graph the browser's CSS source. In dev, let Vite middleware inject the styles. The current backend-integration guide shows the manifest traversal and CSS order: https://vite.dev/guide/backend-integration.html

0 replies

chzaeem47 · 2026-08-30T21:01:46Z

chzaeem47
Aug 30, 2026

I would avoid generating the stylesheet from the SSR build and hardcoding style.css.

The SSR build's job is to produce the server-renderable JS. The browser should use the CSS generated by the client build, because that's the graph that corresponds to the code actually running in the browser.

A typical setup is:

// client vite config
export default defineConfig({
  build: {
    manifest: true,
    cssCodeSplit: true,
  },
})

Then your production build produces something like:

{
  "src/entry-client.tsx": {
    "file": "assets/entry-client-ABC123.js",
    "isEntry": true,
    "css": [
      "assets/entry-client-XYZ789.css"
    ],
    "imports": [
      "_shared-DEF456.js"
    ]
  },
  "_shared-DEF456.js": {
    "file": "assets/shared-DEF456.js",
    "css": [
      "assets/shared-GHI789.css"
    ]
  }
}

During SSR, read the client's .vite/manifest.json and collect:

manifest[clientEntry].css
css from every recursively imported chunk in manifest[clientEntry].imports

Then render:

{cssFiles.map((file) => (
  <link
    key={file}
    rel="stylesheet"
    href={`/static/${file}`}
  />
))}

This is important because CSS can belong to an imported/shared chunk, not just the entry itself. Vite's backend integration documentation describes this recursive imports -> css traversal explicitly.

I would also remove:

cssCodeSplit: false

from the client build. Vite's default is true, and with splitting enabled CSS remains associated with the chunks that use it.

And definitely remove:

assetFileNames: "[name][extname]"

for the production client build. That overrides the normal hashed asset naming, which defeats the main benefit of content-hashed assets.

You can keep the SSR build separate, for example:

// client
{
  build: {
    outDir: "dist/client",
    manifest: true,
    cssCodeSplit: true,
  }
}

// server
{
  build: {
    outDir: "dist/server",
    ssr: true,
  },
}

Then:

src/entry-client.tsx
        ↓
   CLIENT BUILD
        ↓
 hashed JS + hashed CSS
        ↓
   manifest.json
        ↓
      SSR
        ↓
 <link rel="stylesheet"
       href="/static/assets/...hash.css">

For development, you don't need to reproduce this manifest logic. Let Vite's dev server handle CSS/HMR through its middleware.

So the important distinction is:

SSR build → server JS

Client build → browser JS + CSS + manifest

This also keeps your CSS Modules working normally:

import styles from "./root.module.scss";

<Link className={styles.menuItem}>
  Home
</Link>

The generated CSS-module class names and the actual stylesheet both come from the client build, while the SSR build uses the module mapping needed to render the correct class name.

Vite's SSR documentation also recommends separate client and SSR builds for production, with the client build providing the browser assets.

0 replies

Navigation Menu

Uh oh!

Uh oh!

How to properly handle CSS modules for SSR #20903

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 3 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Uh oh!

How to properly handle CSS modules for SSR #20903

Uh oh!

Uh oh!

sbhehe233 Oct 7, 2025

Replies: 3 comments

Uh oh!

official-burak Aug 20, 2026

Uh oh!

Labeeb2339 Aug 27, 2026

Uh oh!

chzaeem47 Aug 30, 2026

sbhehe233
Oct 7, 2025

official-burak
Aug 20, 2026

Labeeb2339
Aug 27, 2026

chzaeem47
Aug 30, 2026