vite-css-modules weekly downloads statistics

vite-css-modules

Vite plugin to fix broken CSS Modules handling.

→ Play with a demo on StackBlitz

[!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

Vite issue #10079, #10340 | Test case

2. Shared classes get duplicated in your bundle

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.

Example:

What happens in Vite:

With this plugin:

Vite issue #7504, #15683 | Test case

3. Missing composes classes fail silently

If you typo a class name in composes, Vite doesn't error. Instead, it outputs undefined in your class names, breaking your UI with no warning.

Example:

What happens in Vite:

With this plugin:

Vite issue #16075 | Test case

4. Can't compose between CSS and SCSS

Trying to compose from SCSS/Sass files causes syntax errors because postcss-modules tries to parse SCSS as plain CSS.

Example:

What happens in Vite:

With this plugin: • Works correctly because each file goes through its proper preprocessor first

Vite issue #10340 | Test case

5. HMR doesn't work properly

Changing a CSS Module file causes a full page reload instead of a hot update, losing component state.

What happens in Vite: • Full page reload on CSS Module changes

With this plugin: • CSS Module changes update instantly without losing component state

Vite issue #16074 | Test case

6. Reserved JavaScript keywords break exports

Using JavaScript reserved keywords as class names (like .import, .export) generates invalid JavaScript code.

Example:

What happens in Vite:

With this plugin: • Properly handles reserved keywords in class names

Vite issue #14050 | Test case

Install

Setup

In your Vite config file, add the patchCssModules() plugin to patch Vite's CSS Modules behavior:

This patches your Vite to handle CSS Modules in a more predictable way.

Configuration

Configuring the CSS Modules behavior remains the same as before.

Read the Vite docs to learn more.

Type checking & navigation for CSS Modules

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:

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:

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 | Use a specific vite.config.* file | | --mode | Set the Vite mode used when loading config | | --silent, -s | Suppress success output (errors still print to stderr) |

Examples

FAQ

What issues does this plugin address?

Vite delegates bundling each CSS Module to postcss-modules, leading to significant problems:

1. CSS Modules not integrated into Vite's build…

Description from the npm listing.