Registry / web-framework / css-modules-typescript-loader

css-modules-typescript-loader

library4.0.1jsnpmunverified

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.

web-framework

npm install css-modules-typescript-loader

github ↗package ↗

INSTALL

IMPORT

SIG · CSS-MODULES-TYPESC

css-modules-typescript-loader

web-frameworkjavascriptv4.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

'css-modules-typescript-loader'

✓ use: ['css-loader', 'css-modules-typescript-loader']

✗ use: ['css-modules-typescript-loader', 'css-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)

✓ { loader: 'css-modules-typescript-loader', options: { mode: 'emit' } }

✗ { loader: 'css-modules-typescript-loader', options: { mode: 'generate' } }

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)

✓ { loader: 'css-modules-typescript-loader', options: { mode: process.env.CI ? 'verify' : 'emit' } }

✗ { loader: 'css-modules-typescript-loader', options: { mode: true } }

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.

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' };

Debug

Known issues

breakingMajor 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.

affects: >=2.0.0

breakingSupport 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`).

affects: <4.0.1

gotchaUsing 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.

affects: >=1.0.0

gotchaThe 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`.

affects: >=1.0.0

gotchaOlder 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.

affects: <2.0.4

Errors

Common errors & fixes

Error: [css-modules-typescript-loader] Generated declaration file does not match committed file.

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.

`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.

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

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.

Upgrade

Version history

4.0.1latest on npm

Audit

Dependencies

css-loaderrequiredThis 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.

loader-utilsrequiredA runtime dependency for Webpack loader utilities; was a missing dependency in older versions of this package.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/seek-oss/css-modules-typescript-loader ↗

packagehttps://www.npmjs.com/package/css-modules-typescript-loader ↗