CSS Modules TypeScript Loader

4.0.1 · maintenance · verified Sun Apr 19

css-modules-typescript-loader is a Webpack loader designed to generate TypeScript declaration files (.d.ts) for CSS Modules. This enables developers to achieve type-safe access to CSS class names within their TypeScript projects, preventing runtime errors due to mistyped or non-existent class references. The current stable version, 4.0.1, was released in September 2020. While lacking a rigid release schedule, previous major updates occurred roughly annually. A key differentiator of this loader is its emphasis on checking the generated TypeScript declarations into source control. This approach facilitates parallel execution of `webpack` and `tsc` commands in Continuous Integration (CI) pipelines, optimizing build times. Furthermore, it offers a unique `verify` mode, which, when enabled, ensures that the committed TypeScript declarations remain in sync with the dynamically generated types, providing an additional layer of consistency assurance.

Common errors

```
Error: [css-modules-typescript-loader] Generated declaration file does not match committed file.
```
cause The `.d.ts` file generated by Webpack during the current build differs from the version committed to source control. This error occurs when the loader is running in `verify` mode.

fix Run your Webpack build in `emit` mode (e.g., `webpack --env mode=emit`) to regenerate the `.d.ts` files, then commit the updated files to version control. Alternatively, disable `verify` mode for local development.
```
Module parse failed: Unexpected token / You may need an appropriate loader to handle this file type.
```
cause `css-modules-typescript-loader` is receiving raw CSS content instead of the processed output from `css-loader`, typically because it's positioned incorrectly in the `use` array or `css-loader` is not configured for modules.

fix Ensure `css-modules-typescript-loader` is placed *after* `css-loader` in your `webpack.config.js` rules. Also, verify that `css-loader` has `options: { modules: true }` enabled.
```
TS2307: Cannot find module './my-component.css' or its corresponding type declarations.
```
cause TypeScript is unable to locate the declaration file for your CSS Module, or the declaration file has not been generated.

fix Confirm that `css-modules-typescript-loader` is correctly configured and running in `emit` mode in your Webpack setup. Ensure your `tsconfig.json` includes the directory where `.d.ts` files are emitted (e.g., `"include": ["./src/**/*.ts", "./src/**/*.tsx", "./src/**/*.d.ts"]`).
```
Webpack compilation error: Cannot read properties of undefined (reading 'getOptions')
```
cause This error often indicates an incompatibility between `css-modules-typescript-loader` and the `css-loader` version, particularly when using `css-loader` v4 or higher with older `css-modules-typescript-loader` versions. It could also be a missing `loader-utils` dependency in very old versions.

fix Upgrade `css-modules-typescript-loader` to v4.0.1 or newer. If on an older version, ensure it's at least v2.0.4 to resolve the `loader-utils` dependency issue.

Warnings

breaking Major template updates in v2.0.0, v3.0.0, and v4.0.0 significantly altered the structure of generated `.d.ts` files. Specifically, v2.0.0 allowed all class name characters, v3.0.0 changed `var` to `declare const`, and v4.0.0 included another template update. Upgrading across these major versions will require regenerating and potentially re-committing type declarations.
Fix: Remove existing `.d.ts` files, upgrade the loader, and rebuild your project to generate new, compatible declarations. Review generated types for any unexpected changes.
breaking Support for `css-loader` v4 was introduced in `css-modules-typescript-loader` v4.0.1. Prior versions of this loader are not compatible with `css-loader` v4 and will likely cause build failures or incorrect type generation.
Fix: Upgrade `css-modules-typescript-loader` to v4.0.1 or newer if you are using `css-loader` v4 or higher. Ensure your `css-loader` options are correctly configured for CSS Modules (`modules: true`).
gotcha Using the `verify` mode (e.g., in CI environments) will cause the Webpack build to fail if any generated TypeScript declaration file does not exactly match its committed counterpart. This is by design but can halt builds if declarations are not consistently updated or committed.
Fix: Ensure all generated `.d.ts` files are committed to source control. During local development, consider setting `mode: 'emit'` or only enabling `verify` mode conditionally (e.g., `process.env.CI ? 'verify' : 'emit'`). Regularly run a build in `emit` mode to update types.
gotcha The loader *must* be placed directly after `css-loader` in the Webpack configuration's `use` array. Misplacement will result in the loader receiving incorrect input (raw CSS instead of CSS Modules' processed output) and failing to generate proper types.
Fix: Review your `webpack.config.js` and ensure `css-modules-typescript-loader` appears immediately after the `css-loader` instance that is configured for `modules: true`.
gotcha Older versions of `css-modules-typescript-loader` (prior to v2.0.4) had a missing `loader-utils` dependency, which could lead to runtime errors during Webpack compilation.
Fix: Upgrade `css-modules-typescript-loader` to v2.0.4 or higher to resolve the missing dependency.

Install

npm install css-modules-typescript-loader npm
yarn add css-modules-typescript-loader yarn
pnpm add css-modules-typescript-loader pnpm

Imports

'css-modules-typescript-loader'
wrong:
```
use: ['css-modules-typescript-loader', 'css-loader']
```
correct:
```
use: ['css-loader', 'css-modules-typescript-loader']
```
Used as a string in the Webpack `module.rules[].use` array. This loader does not export any JavaScript symbols for direct import into application code. It must be chained directly *after* `css-loader` (configured with `modules: true`) to correctly process its output.
css-modules-typescript-loader (with 'emit' mode)
wrong:
```
{ loader: 'css-modules-typescript-loader', options: { mode: 'generate' } }
```
correct:
```
{ loader: 'css-modules-typescript-loader', options: { mode: 'emit' } }
```
The `emit` mode (which is the default) instructs the loader to generate `.d.ts` files. This is the typical mode for development and build environments where types are created or updated.
css-modules-typescript-loader (with 'verify' mode)
wrong:
```
{ loader: 'css-modules-typescript-loader', options: { mode: true } }
```
correct:
```
{ loader: 'css-modules-typescript-loader', options: { mode: process.env.CI ? 'verify' : 'emit' } }
```
The `verify` mode compares generated `.d.ts` files with existing ones and throws an error if they do not match. It is commonly used in CI environments to ensure type consistency and prevent uncommitted type declaration changes.

Quickstart

This Webpack configuration demonstrates how to integrate `css-modules-typescript-loader` to generate TypeScript declaration files for CSS Modules, ensuring type safety for CSS class names within a TypeScript project.

const path = require('path');

module.exports = {
  mode: 'development',
  entry: './src/index.ts',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx', '.css']
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/
      },
      {
        test: /\.css$/,
        use: [
          {
            loader: 'css-loader',
            options: {
              modules: true, // Enable CSS Modules
              importLoaders: 1 // Number of loaders applied before CSS loader
            }
          },
          // This loader MUST come directly after css-loader
          {
            loader: 'css-modules-typescript-loader',
            options: {
              // Use 'verify' in CI to ensure types are up-to-date
              mode: process.env.CI ? 'verify' : 'emit'
            }
          }
        ]
      }
    ]
  },
  devtool: 'source-map'
};

view raw JSON →