{"id":10694,"library":"css-modules-typescript-loader","title":"CSS Modules TypeScript Loader","description":"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.","status":"maintenance","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/seek-oss/css-modules-typescript-loader","tags":["javascript"],"install":[{"cmd":"npm install css-modules-typescript-loader","lang":"bash","label":"npm"},{"cmd":"yarn add css-modules-typescript-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add css-modules-typescript-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This loader processes the output from css-loader (configured for CSS Modules) to generate TypeScript types. It must be placed directly after css-loader in the Webpack configuration.","package":"css-loader","optional":false},{"reason":"A runtime dependency for Webpack loader utilities; was a missing dependency in older versions of this package.","package":"loader-utils","optional":false}],"imports":[{"note":"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.","wrong":"use: ['css-modules-typescript-loader', 'css-loader']","symbol":"'css-modules-typescript-loader'","correct":"use: ['css-loader', 'css-modules-typescript-loader']"},{"note":"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.","wrong":"{ loader: 'css-modules-typescript-loader', options: { mode: 'generate' } }","symbol":"css-modules-typescript-loader (with 'emit' mode)","correct":"{ loader: 'css-modules-typescript-loader', options: { mode: 'emit' } }"},{"note":"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.","wrong":"{ loader: 'css-modules-typescript-loader', options: { mode: true } }","symbol":"css-modules-typescript-loader (with 'verify' mode)","correct":"{ loader: 'css-modules-typescript-loader', options: { mode: process.env.CI ? 'verify' : 'emit' } }"}],"quickstart":{"code":"const path = require('path');\n\nmodule.exports = {\n  mode: 'development',\n  entry: './src/index.ts',\n  output: {\n    path: path.resolve(__dirname, 'dist'),\n    filename: 'bundle.js'\n  },\n  resolve: {\n    extensions: ['.ts', '.tsx', '.js', '.jsx', '.css']\n  },\n  module: {\n    rules: [\n      {\n        test: /\\.tsx?$/,\n        use: 'ts-loader',\n        exclude: /node_modules/\n      },\n      {\n        test: /\\.css$/,\n        use: [\n          {\n            loader: 'css-loader',\n            options: {\n              modules: true, // Enable CSS Modules\n              importLoaders: 1 // Number of loaders applied before CSS loader\n            }\n          },\n          // This loader MUST come directly after css-loader\n          {\n            loader: 'css-modules-typescript-loader',\n            options: {\n              // Use 'verify' in CI to ensure types are up-to-date\n              mode: process.env.CI ? 'verify' : 'emit'\n            }\n          }\n        ]\n      }\n    ]\n  },\n  devtool: 'source-map'\n};\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`).","message":"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.","severity":"breaking","affected_versions":"<4.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade `css-modules-typescript-loader` to v2.0.4 or higher to resolve the missing dependency.","message":"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.","severity":"gotcha","affected_versions":"<2.0.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error: [css-modules-typescript-loader] Generated declaration file does not match committed file."},{"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.","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.","error":"Module parse failed: Unexpected token / You may need an appropriate loader to handle this file type."},{"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\"]`).","cause":"TypeScript is unable to locate the declaration file for your CSS Module, or the declaration file has not been generated.","error":"TS2307: Cannot find module './my-component.css' or its corresponding type declarations."},{"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.","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.","error":"Webpack compilation error: Cannot read properties of undefined (reading 'getOptions')"}],"ecosystem":"npm"}