vite-css-modules

To patch Vite's CSS Modules behavior, add the patchCssModules() plugin to your vite.config.js (or .ts). You should also ensure your build target is set to at least es2022 for optimal results. Configuration for CSS Modules itself remains handled via standard Vite css.modules or lightningcss settings.

// vite.config.js
import { 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
        target: 'es2022'
    }
}

Install the plugin as a development dependency using npm:

npm install -D vite-css-modules

You can generate .d.ts files for your CSS Modules to enable autocomplete and type checking in TypeScript. To enable "Go to Definition" (jumping from a TS class name to the CSS source), you must enable both generateSourceTypes and declarationMap.

patchCssModules({
    generateSourceTypes: true,
    declarationMap: true
})

By default, CSS class names containing special characters (like hyphens in .foo-bar) cannot be used as named exports in older JavaScript environments because they are invalid variable names.

You have two primary ways to handle this:

1. Use camelCase convention

Set the localsConvention to camelCase in your Vite configuration. This automatically converts kebab-case class names into camelCase named exports.

2. Use ES2022 named exports

If you set your build target to es2022, you can use arbitrary strings as named exports by using quotes in your import statement. This allows you to import .foo-bar directly without changing the naming convention.

// vite.config.js
export default {
    build: {
        target: 'es2022'
    }
}

// Usage in your component
import { 'foo-bar' as fooBar } from './styles.module.css'

console.log(fooBar) // Outputs the class name

The patchCssModules(options) function accepts the following configuration options:

• exportMode: Determines how class names are exported. Defaults to 'both'.
  • '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: A boolean that, when true, generates a .d.ts file next to each CSS Module. Defaults to false.
• declarationMap: A boolean that generates inline declaration source maps in .d.ts files to enable "Go to Definition". Defaults to auto-detection from tsconfig.json's compilerOptions.declarationMap. Requires generateSourceTypes: true.

The following flags are available for the vite-css-modules CLI:

| 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) |

The CLI allows you to generate TypeScript declarations for CSS Modules without running a full build. It requires patchCssModules() to be present in your Vite config.

Usage: npx vite-css-modules [globs...] [--config path] [--mode mode]

• If no globs are provided, it defaults to **/*.module.{css,scss,sass} under the Vite root.
• If globs are provided, they are resolved from the current working directory.
• The CLI uses your existing vite.config.* file.

# Generate types for CSS Modules under the Vite root
npx vite-css-modules

# Use explicit globs from the current working directory
npx vite-css-modules 'src/**/*.module.css'

# Use a specific Vite config
npx vite-css-modules 'src/**/*.module.css' --config apps/web/vite.config.ts

# Load config with production mode
npx vite-css-modules 'src/**/*.module.css' --mode production

The cssModules function is the primary entry point for creating the Vite plugin. It is designed to be used by Vite internally, taking the ResolvedConfig and an optional PatchConfig to return a Vite Plugin instance.

Note: This function is intended for internal Vite usage rather than direct end-user plugin registration in a standard vite.config.ts.

import { cssModules } from 'vite-css-modules';

// Internal usage pattern
const plugin = cssModules(resolvedConfig, patchConfig);