CSS Modules: `@extend` (postcss-extend-rule) silently dropped — CSS-Modules plugin runs before user PostCSS plugins

[james-elicx]

Problem

@extend from postcss-extend-rule is silently discarded in CSS Modules. Every declaration the rule should have inherited is missing — in dev and in the production build alike — with no warning or error.

/* styles.module.css */
.shared { position: absolute; visibility: hidden; }
.wrap   { @extend .shared; border: 1px solid red; }

Expected: .wrap inherits position: absolute; visibility: hidden.

Actual output:

._shared_1u9uh_1{visibility:hidden;position:absolute}
._wrap_1u9uh_2{border:1px solid red}

The at-rule is gone and nothing was copied.

Cause

Vite's compileCSS puts the CSS-Modules plugin at the front of the PostCSS chain:

if (isModule) postcssPlugins.unshift((await importPostcssModules()).default({ ... }))

So class names are already hashed to ._shared_1u9uh_1 by the time the project's postcss-extend-rule runs. @extend .shared matches no rule, and the plugin drops it silently.

Running the same PostCSS config standalone over the same file resolves the extend correctly, so the configuration is fine — only the ordering inside Vite's pipeline is wrong.

Reproduction (no vinext involved)

postcss.config.mjs   ->  export default { plugins: { 'postcss-extend-rule': {} } }
src/styles.module.css -> the two rules above
src/main.js          ->  import s from "./styles.module.css"
vite build

The emitted CSS shows _wrap_ without the extended declarations. This reproduces on plain Vite with no vinext in the project, so the underlying issue is Vite's plugin ordering — filing here because vinext already resolves and injects the project's PostCSS config, and is where a Next-compatible pipeline would be expected to handle it (webpack/css-loader runs the user's PostCSS before CSS-Modules scoping, so the same stylesheet works under next build).

Impact

Any CSS module using @extend loses those declarations. In one Pages Router app this silently affected 46 @extend uses across 11 module files, producing components with missing positioning — dropdown panels rendering in flow instead of as absolutely-positioned overlays, etc. Because nothing warns, it presents as "the CSS is just wrong" with no obvious cause.

Workaround

Expanding @extend before Vite's pipeline sees the file, via an enforce: "pre" transform, fixes it — the extend resolves against the original selectors and Vite then hashes the already-expanded rules:

const expandCssModuleExtends = () => {
  let processor;
  return {
    name: "expand-css-module-extends",
    enforce: "pre" as const,
    async transform(code: string, id: string) {
      const file = id.split("?")[0];
      if (!file.endsWith(".module.css") || !code.includes("@extend")) return null;
      if (!processor) {
        const postcss = (await import("postcss")).default;
        const extendRule = (await import("postcss-extend-rule")).default;
        const presetEnv = (await import("postcss-preset-env")).default;
        // `@extend` must see flat selectors: postcss-extend-rule skips nested
        // rules whose selector it cannot resolve, so flatten nesting first.
        processor = postcss([
          presetEnv({ stage: false, features: { "nesting-rules": true } }),
          extendRule(),
        ]);
      }
      const result = await processor.process(code, { from: file });
      return { code: result.css, map: null };
    },
  };
};

Note the nesting step — without it only the @extends at one nesting depth are expanded, which looks like a partial fix.

Environment

• vinext 1.0.0-beta.6
• Vite 8.1.0
• postcss-extend-rule, postcss-preset-env
• Reproduced in dev and in the production build, and on plain Vite without vinext

[james-elicx]

I think we probably need to create a proper reproduction in this repo and test out whether using https://github.com/privatenumber/vite-css-modules in a user's vite config resolves the issue as a workaround.

[james-elicx]

Follow-up: vite-css-modules fixes this properly, but needs one workaround under vinext

vite-css-modules addresses the root cause rather than working around it — it routes CSS Modules through the module graph so the project's PostCSS plugins run before class scoping. With it, @extend resolves correctly:

/* stock Vite — extend dropped */
._shared_1u9uh_1{visibility:hidden;position:absolute}._wrap_1u9uh_2{border:1px solid red}

/* with patchCssModules() — extend applied */
._shared_2cf912d,._wrap_cb17ab4{visibility:hidden;position:absolute}._wrap_cb17ab4{border:1px solid red}

It also fixes the CSS-Module full-page-reload on edit (hot update instead), plus composes dedup and silent undefined on typo'd class names.

However, with its defaults a Pages Router app renders completely unstyled in dev under vinext.

vinext builds ssr (workerd) and client as separate environments, and the plugin's default scoped name — _[local]_[hash:7] — hashes something environment-specific. The two environments therefore generate different names for the same file, so the server-rendered markup carries class names the client stylesheet never defines:

DOM (server-rendered):   _contentWrapper_64e7bcc
Client stylesheet has:   _contentWrapper_1eab870
rules matching DOM class: 0

Every element is unstyled, with no error or warning — the dev-served CSS looks correct in isolation, which makes it hard to spot.

Workaround: make the scoped name a pure function of the file path, so both environments must agree.

import { createHash } from "node:crypto";
import path from "node:path";

export default defineConfig({
  plugins: [patchCssModules(), vinext(), cloudflare()],
  css: {
    modules: {
      generateScopedName: (name: string, filename: string) => {
        const rel = path
          .relative(repoRoot, filename.split("?")[0])
          .replaceAll("\\", "/");
        const hash = createHash("sha256").update(rel).digest("hex").slice(0, 7);
        return `_${name}_${hash}`;
      },
    },
  },
});

It has to be a function — passing the string form (e.g. "[name]__[local]___[hash:base64:5]") still resolves the hash placeholder per-environment and the mismatch persists. Hashing only the repo-relative path is what guarantees agreement.

With that in place, dev and the production build both render correctly:

	dev (workerd)	production build
scoped-name match	✅	✅
hydration error	none	none
CSS finishing after FCP	—	0

Whether the right fix lives in vinext (aligning CSS-Module scoping across its environments) or in the plugin (making the default hash environment-independent) is for the maintainers, but the current default combination silently produces an unstyled app.

[james-elicx]

Second finding: CSS classes named default collide with the ES default export

Also worth recording for anyone adopting vite-css-modules here. A stylesheet with a class literally named default — common for a component's default variant:

.myComponent.default .panel { /* ... */ }

produces a warning under the plugin's exportMode: "both":

warning: With `exportMode: both`, you cannot use "default" as a class name
as it conflicts with the default export. Set `exportMode` ...

The class is dropped, so anything reading styles.default gets the module's default export (the class map) rather than the class name, and that variant silently loses its styles. It fails quietly — the page renders, just unstyled in that branch.

Setting exportMode: "default" resolves it for codebases that access classes via a default import (import styles from "./x.module.css"; styles.default):

patchCssModules({ exportMode: "default" })

Warnings drop to zero and the variant styles apply.

One note in case it saves someone time: I initially blamed this setting for breaking dev, when the real cause was the scoped-name divergence described in the previous comment. The two present identically — an unstyled page — so they are easy to confound. Fix the scoped names first, then evaluate exportMode.

[NriotHrreion]

So should we auto-install vite-css-modules during vinext init when css modules are detected, or just let the user decide? I think auto-installing it with a message informing the user would be a better approach.

I'd be happy to work on this.

[james-elicx]

Yes I agree we should auto-install it. I think we should also auto-setup the generateScopedName part that I had to do in a separate app as well otherwise people will still have issues in pages router apps (not tested in app router). Definitely agree we will need a message informing users about it