[!NOTE]
We're working to integrate this fix directly into Vite (PR #16018). Until then, use this plugin to benefit from these improvements now.
Why use this plugin?
Have you encountered any of these Vite CSS Module bugs? They're happening because Vite's CSS Modules implementation delegates everything to postcss-modules, creating a black box that Vite can't see into.
This plugin fixes these issues by properly integrating CSS Modules into Vite's build pipeline.
The bugs this fixes
1. PostCSS plugins don't apply to composes dependencies
When you use composes to import classes from another CSS file, Vite's PostCSS plugins never process the imported file. This means your PostCSS transformations, auto-prefixing, or custom plugins are silently skipped for dependencies.
What happens in Vite:
style.module.css gets processed by PostCSS ✓
utils.css does NOT get processed by PostCSS ✗
Your PostCSS plugin never sees utils.css because postcss-modules bundles it internally
With this plugin:
Both files go through your PostCSS pipeline correctly
When multiple CSS Modules compose from the same utility file, the utility's styles get bundled multiple times. This increases bundle size and can cause style conflicts.
In your Vite config file, add the patchCssModules() plugin to patch Vite's CSS Modules behavior:
// vite.config.jsimport { patchCssModules } from 'vite-css-modules'export default { plugins: [ patchCssModules() // ← This is all you need to add! // Other plugins... ], css: { // Your existing CSS Modules configuration modules: { // ... }, // Or if using LightningCSS lightningcss: { cssModules: { // ... } } }, build: { // Recommended minimum target (See FAQ for more details) target: 'es2022' }}
This patches your Vite to handle CSS Modules in a more predictable way.
Configuration
Configuring the CSS Modules behavior remains the same as before.
This plugin can generate type definition (.d.ts) files for CSS Modules, providing autocomplete and type checking for class names. For example, importing style.module.css will create a style.module.css.d.ts next to it:
patchCssModules({ generateSourceTypes: true})
Go to CSS Definition
Add declarationMap to include inline source maps in the generated .d.ts files:
This enables "Go to Definition" (F12 / Cmd+Click in VS Code) to jump from a CSS class name in TypeScript directly to where it's defined in the CSS file. Without declaration maps, "Go to Definition" lands on the generated .d.ts — a machine-generated file with no useful context.
When not explicitly set, declarationMap auto-detects from tsconfig.json's compilerOptions.declarationMap.
API
patchCssModules(options)
exportMode
Type: 'both' | 'named' | 'default'
Default: 'both'
Specifies how class names are exported from the CSS Module:
both: Exports class names as both named and default exports.
named: Exports class names as named exports only.
default: Exports class names as a default export only (an object where keys are class names).
generateSourceTypes
Type: boolean
Default: false
Generates a .d.ts file next to each CSS Module with type definitions for the exported class names.
declarationMap
Type: boolean
Default: Auto-detected from tsconfig.json's compilerOptions.declarationMap
Generates inline declaration source maps in .d.ts files, enabling "Go to Definition" to navigate from TypeScript to CSS source. Requires generateSourceTypes to be enabled.
[!TIP]
Source maps are always inlined rather than emitted as separate .d.ts.map files. Since .d.ts files are generated in-place next to your CSS source, external map files would pollute the source directory. The size overhead of inlining is negligible for typical CSS modules.
CLI
Generate TypeScript declarations for CSS Modules without running a build.
The CLI expects a vite.config.* file in the current working directory and uses that one config for every matched file.
With no globs, the CLI defaults to:
**/*.module.{css,scss,sass}
and searches under the resolved Vite root.
When you pass globs explicitly, they are resolved from the current working directory instead.
Run it from the same cwd you would use for vite, or pass --config to point at a specific config file. Use --mode when your Vite config depends on the active mode.
The CLI requires patchCssModules() in your Vite config and reads its options (exportMode, declarationMap) along with Vite's css.modules settings.
Flags
Flag
Description
--config <path>
Use a specific vite.config.* file
--mode <mode>
Set the Vite mode used when loading config
--silent, -s
Suppress success output (errors still print to stderr)
Examples
# Generate types for CSS Modules under the Vite rootnpx vite-css-modules# Use explicit globs from the current working directorynpx vite-css-modules 'src/**/*.module.css'# Use a specific Vite confignpx vite-css-modules 'src/**/*.module.css' --config apps/web/vite.config.ts# Load config with production modenpx vite-css-modules 'src/**/*.module.css' --mode production
FAQ
What issues does this plugin address?
Vite delegates bundling each CSS Module to postcss-modules, leading to significant problems:
CSS Modules not integrated into Vite's build
Since postcss-modules is a black box that only returns the final bundled output, Vite plugins can't hook into the CSS Modules build or process their internal dependencies. This prevents post-processing by plugins like SCSS, PostCSS, or LightningCSS. (#10079, #10340)
The vite-css-modules plugin fixes these issues by seamlessly integrating CSS Modules into Vite's build process.
How does this work?
The plugin treats CSS Modules as JavaScript modules, fully integrating them into Vite's build pipeline. Here's how:
Transforms CSS into JS modules
CSS Modules are compiled into JS files that load the CSS. composes rules become JS imports, and class names are exported as named JS exports.
Integrates with Vite's module graph
Because they're now JS modules, CSS Modules join Vite's module graph. This enables proper dependency resolution, bundling, and de-duplication.
Unlocks plugin compatibility
Other Vite plugins can now access and process CSS Modules—fixing the prior limitation where dependencies inside them were invisible.
This model is similar to Webpack's css-loader, making it familiar to devs transitioning from Webpack. It also reduces overhead and improves performance in larger projects.
Does it export class names as named exports?
Yes, but there are a few things to keep in mind:
JavaScript naming restrictions
Older JavaScript versions don't allow special characters (like -) in variable names. So a class like .foo-bar couldn't be imported as foo-bar and had to be accessed via the default export.
Using localsConvention
To work around this, set css.modules.localsConvention: 'camelCase' in your Vite config. This converts foo-bar → fooBar, making it a valid named export.
ES2022 support for arbitrary names
With ES2022, you can now export/import names with any characters using quotes. This means .foo-bar can be used as a named export directly.
postcss-modules fails silently when it can't resolve a composes dependency—missing exports don't throw errors, making CSS bugs harder to catch. (#16075)
Crash on circular composes dependencies
When two CSS Modules compose from each other, postcss-modules triggers a deadlock that crashes the build with an unhelpful internal error. This plugin detects the cycle and throws a descriptive error showing the dependency chain (e.g. Circular CSS Module dependency: "a.module.css" -> "b.module.css" -> "a.module.css").