vite-plugin-css-module-types

Vite dev-server plugin that generates .d.ts declarations for CSS Modules. With css.devSourcemap enabled, includes JSDoc links to original CSS source lines and declaration maps for "Go to Definition".

Inspired by vite-plugin-css-module-dts and typed-css-modules.

Quick start

// vite.config.ts
import viteCssModuleTypesPlugin from 'vite-plugin-css-module-types';

export default defineConfig({
  css: { devSourcemap: true },
  plugins: [
    viteCssModuleTypesPlugin({
      dtsOutputDir: 'tmp/vite-plugin-css-module-types', // add to .gitignore
      include: ['apps/web/src'],
      exclude: ['apps/web/src/legacy'],
    }),
  ],
});

Add to your .gitignore:

tmp/vite-plugin-css-module-types/

Add to your tsconfig.json:

{
  "compilerOptions": {
    "rootDirs": [
      "./src",
      "./tmp/vite-plugin-css-module-types/src"
    ]
  },
  "include": [
    "**/*.ts",
    "**/*.tsx",
    "tmp/vite-plugin-css-module-types/src"
  ]
}

If you use /src in your rootDirs (as in the example above), it's best to also add the corresponding path from the output directory (e.g., ./tmp/vite-plugin-css-module-types/src) to avoid issues with path mapping.

Runs only in serve mode. Processes *.module.css files.

Options

| Option | Type | Default | Description | | -------------------------- | -------------------- | ----------- | -------------------------------------------------------------------- | | dtsOutputDir | string | — | Required. Output directory for .d.ts files, relative to root. | | include | string \| string[] | undefined | Folder(s) to include (prefix-matched). | | exclude | string \| string[] | undefined | Folder(s) to exclude. Wins when both match. | | namedExports | boolean | false | Emit export declare const per class. | | allowArbitraryExtensions | boolean | false | Use TS 5.0+ .d.module.css.ts naming instead of .module.css.d.ts. | | declarationMap | boolean | true | Generate .d.ts.map for "Go to Definition". Needs devSourcemap. |

Path matching is prefix-based (not glob). Separators are normalized, ./ and trailing / are stripped.

Output examples

Default mode

declare const styles: {
  /** [↗ button.module.css:3](file:///abs/path/button.module.css#L3) */
  readonly 'btn-primary': '_btn-primary_x1y2z';
};
export default styles;

With namedExports: true

/** [↗ button.module.css:3](file:///abs/path/button.module.css#L3) */
export declare const btnPrimary: string;

declare const styles: {
  readonly 'btn-primary': '_btn-primary_x1y2z';
  readonly btnPrimary: '_btn-primary_x1y2z';
};
export default styles;

With CSS docblock comments

/** Main call-to-action button. */
.btn-primary { color: blue; }

declare const styles: {
  /**
   * ```txt
   * Main call-to-action button.
   * ```
   * ---
   * ```css
   * .btn-primary { color: blue; }
   * ```
   * ---
   * [↗ button.module.css:2](file:///abs/path/button.module.css#L2)
   */
  readonly 'btn-primary': '_btn-primary_x1y2z';
};
export default styles;

Empty module

export {};

Dependencies

• source-map — inline CSS sourcemap parsing
• @jridgewell/sourcemap-codec — VLQ encoding for declaration maps
• Vite ^8 (peer), TypeScript ^5 (peer)