skip to content

After a Vite config sets `css.transformer: 'lightningcss'`, why do postcss.config.js plugins and `css.modules` naming options silently stop applying?

level: seniorimportance: nice to knowfreq 4%

answer

  1. one engine per CSS stage
  2. postcss is the default transformer
  3. PostCSS config no longer loaded
  4. css.modules feeds postcss-modules
  5. css.lightningcss.cssModules instead

basics

~20 s

css.transformer picks the engine for CSS processing. With 'lightningcss', Vite hands each stylesheet to Lightning CSS instead of PostCSS, so PostCSS config and plugins never run, and CSS Modules naming moves to css.lightningcss.cssModules; css.modules feeds postcss-modules only.

solid answer

~40 s

`css.transformer` picks the engine Vite uses to process CSS: `'postcss'` by default, or the experimental `'lightningcss'`. With `'lightningcss'`, Vite still runs a preprocessor such as Sass first, but passes the result to Lightning CSS instead of PostCSS, so `postcss.config.js`, an inline `css.postcss` and every plugin in them stop running - with no error, just output missing what they did. `.module.css` files are still scoped, but `css.modules` configures postcss-modules and no longer has any effect; naming options move to `css.lightningcss.cssModules`, and the generated class names change. Lightning CSS's own settings, such as `targets`, go under `css.lightningcss`. Before switching, list what each PostCSS plugin did and confirm the replacement covers it.

go deeper

for a junior

Recall that css.transformer chooses between PostCSS, the default, and Lightning CSS for processing stylesheets in a Vite project.

for a middle

Explain that the two engines are alternatives, so the PostCSS config stops loading, and that CSS Modules options live under css.lightningcss.cssModules instead.

for a senior

Show you would inventory PostCSS plugins, diff built CSS and check tests that depend on generated class names before switching an experimental option.

for a principal

Weigh faster CSS processing against plugin coverage and an experimental flag across many apps, and decide who owns that migration and its rollback.

## One switch, two engines Vite processes every imported stylesheet in two stages: first a **preprocessor** when the file needs one (Sass, Less, Stylus), then a **CSS transformer** that handles `@import`, `url()` references, CSS Modules scoping and any further transforms. `css.transformer` chooses the engine for the second stage: | `css.transformer` | Engine | Configured by | CSS Modules options | |---|---|---|---| | `'postcss'` (default) | PostCSS | `postcss.config.js`, or an inline `css.postcss` | `css.modules`, passed to postcss-modules | | `'lightningcss'` (experimental) | Lightning CSS | `css.lightningcss` | `css.lightningcss.cssModules` | For each stylesheet Vite calls one compiler or the other, never both. That is the whole cause of the symptom: the PostCSS path is not run with fewer plugins, it is not run at all. ## What stops when you switch - **Every PostCSS plugin.** Vite no longer loads the PostCSS config, so plugins listed in `postcss.config.js` or an inline `css.postcss` do not run. Nothing fails; the output just lacks their work - vendor prefixes, a nesting transform, a utility-CSS generator wired in as a PostCSS plugin. - **`css.modules`.** Those options configure postcss-modules and have no effect under Lightning CSS. `.module.css` files are still scoped, because Vite enables Lightning CSS's CSS Modules for them by default, but `generateScopedName`, `localsConvention`, `hashPrefix` and the rest are ignored, so generated class names follow Lightning CSS's own scheme. - **PostCSS's `@import` behaviour.** PostCSS's import inlining treats a duplicated `@import` differently from browsers - Vite's docs flag this - so output can change where one file is imported twice. ## What keeps working 1. **Preprocessors.** Sass, Less and Stylus still compile first, with their `css.preprocessorOptions` and `additionalData`; Lightning CSS receives plain CSS. 2. **CSS Modules scoping** for `.module.*` files, configured in its new place. 3. **Minification**, which is a separate build setting and is not chosen by `css.transformer`. ## Which configuration stays live | Setting | Under `'lightningcss'` | |---|---| | `postcss.config.js` | not loaded | | `css.postcss` | not used | | `css.modules` | no effect | | `css.lightningcss` (including `cssModules`) | the processing configuration | | `css.preprocessorOptions`, `additionalData` | still used by the preprocessor stage | | `css.devSourcemap` | still decides whether dev CSS gets source maps | The table is the review checklist for the change: every row marked "not loaded", "not used" or "no effect" that the project actually sets is configuration someone believes is working. ## A switch that breaks tests, not builds Picture the job board's design system. Its `css.modules` uses a `generateScopedName` function so classes read `JobCard__title`, end-to-end tests select on those names, and its `postcss.config.js` adds vendor prefixes. Someone sets `css.transformer: 'lightningcss'` for speed. The build passes and the app renders. Then the end-to-end suite fails, because class names now follow a different pattern, and the prefixing plugin no longer runs, so whether prefixes appear now depends on Lightning CSS's own settings under `css.lightningcss`. Nothing in the build output said that two pieces of configuration had become dead. ## Migrating deliberately 1. **Inventory** every plugin in the PostCSS config and write down what each one does. 2. **Map** each to a Lightning CSS feature or option under `css.lightningcss`, or decide to drop it; if one has no equivalent, stay on `'postcss'`. 3. **Move** CSS Modules naming from `css.modules` to `css.lightningcss.cssModules`, and check everything that depends on generated names - tests, snapshots, global overrides. 4. **Diff** the built CSS before and after the switch, file by file. 5. **Keep it reversible.** The option is marked experimental, so make the change easy to undo. ## How to tell which engine ran - If `css.transformer` is unset or `'postcss'`, the PostCSS config is searched from the project root (or the path in `css.postcss`) and applied to every imported stylesheet. - If it is `'lightningcss'`, edits to `postcss.config.js` change nothing - a quick test when you suspect the switch. ## What interviewers listen for - That `css.transformer` replaces the PostCSS stage rather than adding a step after it. - That `css.modules` belongs to the PostCSS path and has a Lightning CSS counterpart. - That silence, not an error, is the symptom, and a diff of the built CSS is how you find it.

  • Does `css.transformer: 'lightningcss'` in a Vite config stop Sass from compiling `.scss` files?
    No. Vite runs the preprocessor first - Sass, Less or Stylus, including `additionalData` - and only then hands the resulting CSS to Lightning CSS where PostCSS would have run. Only the PostCSS stage is replaced, so preprocessor options keep working unchanged.
  • How would you check what a Vite project loses before switching `css.transformer` to `'lightningcss'`?
    List every plugin in the PostCSS config and what it adds, then build once with each transformer and diff the CSS files. Search tests and global stylesheets for dependence on generated CSS Modules class names. Any plugin without a Lightning CSS equivalent is a reason to stay on `'postcss'`.

  • css.transformer only switches the CSS minifier
  • Vite runs PostCSS plugins first, then Lightning CSS on their output
  • css.modules options carry over unchanged to Lightning CSS
  • Switching to lightningcss turns off scoping for .module.css files
  • Sass stops compiling once Lightning CSS processes the CSS