Registry / type-stubs / typescript-plugin-css-modules

typescript-plugin-css-modules

library5.2.0jsnpmunverified

typescript-plugin-css-modules is a TypeScript language service plugin that enhances developer experience by providing type information and autocomplete for CSS Modules within IDEs. It allows developers to safely use CSS class names, including those from SCSS, Sass, Less, and Stylus files, by inferring types from their module exports. The current stable version is 5.2.0. This plugin primarily focuses on design-time support for tools that leverage TypeScript's language service, such as VS Code, rather than providing compilation-time error checking or direct CSS Module bundling/processing. Its release cadence is generally every few months for minor versions, with patch releases as needed. A key differentiator is its seamless integration with the TypeScript language service to provide strong typing and intellisense for CSS module exports, catching typos and providing auto-completion where standard TypeScript or bundler configurations might only offer generic `[key: string]: string` types.

type-stubs

npm install typescript-plugin-css-modules

github ↗package ↗

INSTALL

IMPORT

SIG · TYPESCRIPT-PLUGIN-

typescript-plugin-css-modules

type-stubsjavascriptv5.2.0

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.

styles

✓ import styles from './my-component.module.css';

✗ const styles = require('./my-component.module.css');

Default import provides an object where CSS class names are properties. This is the primary way to access classes, especially those with hyphens or underscores.

myClass

✓ import { myClass } from './my-component.module.css';

✗ import { my_class } from './my-component.module.css';

Named imports are supported for class names that do not contain hyphens or underscores (e.g., `myClass` for `.myClass`). For classes like `my-other-class` or `my_other_class`, use the default import `styles['my-other-class']` syntax. Named exports can also be combined with default exports.

Global CSS Module Declaration

✓ declare module '*.module.css' { const classes: { [key: string]: string }; export default classes; }

✗ import * as styles from './my-component.module.css';

While not a direct import in your code, adding global declarations for CSS modules (`*.module.css`, `*.module.scss`, etc.) in a `.d.ts` file is often recommended to help TypeScript understand the general shape of imported CSS modules during compilation, even with the plugin. This prevents 'Cannot find module' errors.

This quickstart demonstrates installing the plugin, configuring `tsconfig.json`, and importing CSS Modules with both default and named exports in a React component, providing type safety for class names.

/* src/App.module.css */ .container { display: flex; justify-content: center; align-items: center; height: 100vh; background-color: #f0f0f0; } .title { color: #333; font-size: 2em; } .highlightText { color: #007bff; font-weight: bold; } /* src/App.tsx */ import React from 'react'; import styles, { title, highlightText } from './App.module.css'; interface AppProps { message: string; } const App: React.FC<AppProps> = ({ message }) => { return ( <div className={styles.container}> <h1 className={title}> Hello, <span className={highlightText}>{message}</span>! </h1> </div> ); }; export default App; // tsconfig.json // { // "compilerOptions": { // "plugins": [{ "name": "typescript-plugin-css-modules" }], // "jsx": "react-jsx" // } // } // src/global.d.ts (optional, but recommended for full type safety) // declare module '*.module.css' { // const classes: { readonly [key: string]: string }; // export default classes; // }

Debug

Known issues

breakingVersion 5.0.0 introduced a breaking change requiring TypeScript 4.x as the minimum supported version. Projects using older TypeScript versions must upgrade to at least 4.0.0.

fix

Upgrade your TypeScript dependency to version 4.0.0 or higher in your `package.json` and reinstall dependencies.

affects: >=5.0.0

gotchaThis plugin *only* provides type information to IDEs and does not provide errors during compilation nor adds actual CSS module support to your project build. For compilation, a separate build setup (e.g., Webpack's `css-loader`, Jest transformers) is required.

fix

Ensure your build system (Webpack, Rollup, Vite, etc.) is correctly configured to process CSS Modules at compilation time. This plugin only enhances IDE developer experience.

affects: >=1.0.0

gotchaFor Visual Studio Code users, it is highly recommended to configure VS Code to use the workspace's version of TypeScript, not its bundled version. Failure to do so may result in the plugin not activating or providing incorrect type suggestions.

fix

In VS Code, open the command palette (`Ctrl+Shift+P` or `Cmd+Shift+P`), search for 'TypeScript: Select TypeScript Version', and choose 'Use Workspace Version'.

affects: >=1.0.0

gotchaUsing Sass `@use` rules within SCSS modules might lead to `typescript-plugin-css-modules` reporting an empty interface `{}` for the imported module, causing errors on class names in the IDE. This is a known issue.

fix

Check the project's GitHub issues for updates on `@use` support. A temporary workaround might involve adjusting your SCSS structure or custom matchers if available, or potentially adding explicit type declarations.

affects: >=5.0.0

deprecatedThe `Stylus` renderer became an optional dependency in v5.2.0. If you use Stylus files (`.styl`), you need to explicitly install `stylus` as a dev dependency in your project.

fix

If your project uses Stylus, install it: `npm install --save-dev stylus` or `yarn add -D stylus`.

affects: >=5.2.0

Errors

Common errors & fixes

Cannot find module './my-component.module.css' or its corresponding type declarations.

TypeScript compiler cannot find a `.d.ts` declaration for CSS modules, or the plugin is not correctly configured/loaded.

fix

1. Ensure `typescript-plugin-css-modules` is listed in `compilerOptions.plugins` in `tsconfig.json`. 2. For broader compatibility and to avoid build errors, add global type declarations for CSS modules (e.g., `declare module '*.module.css';`) in a `.d.ts` file in your project.

Property 'myClass' does not exist on type '{ readonly [key: string]: string; }'.

The TypeScript language service plugin is not active, or a generic CSS module declaration is overriding the plugin's specific type inference, meaning the IDE isn't providing specific types for your CSS classes.

fix

Verify `tsconfig.json` plugin configuration. If using VS Code, ensure it's set to 'Use Workspace Version' of TypeScript. Check for conflicting global `.d.ts` declarations that might provide a generic `[key: string]: string` type without the specific class names.

File '/project/src/App.module.scss' is not listed within the file list of project '/project/tsconfig.json'. Projects must list all files or use an 'include' pattern.

This error can occur with TypeScript 5 and `composite: true` when the plugin is active, suggesting an issue with how the plugin interacts with TypeScript's project file discovery for `.scss` modules.

fix

This specific issue (related to TS5 and `composite: true`) points to a bug. Refer to the project's GitHub issues (`mrmckeb/typescript-plugin-css-modules#222`) for the latest status and potential workarounds, which may involve explicit `include` patterns or plugin options.

Upgrade

Version history

5.2.0latest on npm

Audit

Dependencies

typescriptrequiredPeer dependency, required for the TypeScript language service plugin to function. Minimum version >=4.0.0.

stylusoptionalOptional dependency since v5.2.0. Required only if using Stylus CSS modules and the plugin's default renderer.

Agent activity

40 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mrmckeb/typescript-plugin-css-modules ↗

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