{"id":12248,"library":"typescript-plugin-css-modules","title":"CSS Modules Support for TypeScript Language Service","description":"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.","status":"active","version":"5.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/mrmckeb/typescript-plugin-css-modules","tags":["javascript","css","scss","sass","less","stylus","modules","plugin","postcss","typescript"],"install":[{"cmd":"npm install typescript-plugin-css-modules","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-plugin-css-modules","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-plugin-css-modules","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for the TypeScript language service plugin to function. Minimum version >=4.0.0.","package":"typescript","optional":false},{"reason":"Optional dependency since v5.2.0. Required only if using Stylus CSS modules and the plugin's default renderer.","package":"stylus","optional":true}],"imports":[{"note":"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.","wrong":"const styles = require('./my-component.module.css');","symbol":"styles","correct":"import styles from './my-component.module.css';"},{"note":"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.","wrong":"import { my_class } from './my-component.module.css';","symbol":"myClass","correct":"import { myClass } from './my-component.module.css';"},{"note":"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.","wrong":"import * as styles from './my-component.module.css';","symbol":"Global CSS Module Declaration","correct":"declare module '*.module.css' { const classes: { [key: string]: string }; export default classes; }"}],"quickstart":{"code":"/* src/App.module.css */\n.container {\n  display: flex;\n  justify-content: center;\n  align-items: center;\n  height: 100vh;\n  background-color: #f0f0f0;\n}\n\n.title {\n  color: #333;\n  font-size: 2em;\n}\n\n.highlightText {\n  color: #007bff;\n  font-weight: bold;\n}\n\n/* src/App.tsx */\nimport React from 'react';\nimport styles, { title, highlightText } from './App.module.css';\n\ninterface AppProps {\n  message: string;\n}\n\nconst App: React.FC<AppProps> = ({ message }) => {\n  return (\n    <div className={styles.container}>\n      <h1 className={title}>\n        Hello, <span className={highlightText}>{message}</span>!\n      </h1>\n    </div>\n  );\n};\n\nexport default App;\n\n// tsconfig.json\n// {\n//   \"compilerOptions\": {\n//     \"plugins\": [{ \"name\": \"typescript-plugin-css-modules\" }],\n//     \"jsx\": \"react-jsx\"\n//   }\n// }\n\n// src/global.d.ts (optional, but recommended for full type safety)\n// declare module '*.module.css' {\n//   const classes: { readonly [key: string]: string };\n//   export default classes;\n// }\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your TypeScript dependency to version 4.0.0 or higher in your `package.json` and reinstall dependencies.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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'.","message":"For 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Using 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.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"If your project uses Stylus, install it: `npm install --save-dev stylus` or `yarn add -D stylus`.","message":"The `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.","severity":"deprecated","affected_versions":">=5.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"TypeScript compiler cannot find a `.d.ts` declaration for CSS modules, or the plugin is not correctly configured/loaded.","error":"Cannot find module './my-component.module.css' or its corresponding type declarations."},{"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.","cause":"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.","error":"Property 'myClass' does not exist on type '{ readonly [key: string]: string; }'."},{"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.","cause":"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.","error":"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."}],"ecosystem":"npm"}