CSS Modules Support for TypeScript Language Service

Common errors

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

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

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

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

Warnings

• breaking 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.
  Fix: Upgrade your TypeScript dependency to version 4.0.0 or higher in your `package.json` and reinstall dependencies.
• gotcha 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.
  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.
• gotcha 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.
  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'.
• gotcha 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.
  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.
• deprecated 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.
  Fix: If your project uses Stylus, install it: `npm install --save-dev stylus` or `yarn add -D stylus`.

Install

• npm install typescript-plugin-css-modules npm
• yarn add typescript-plugin-css-modules yarn
• pnpm add typescript-plugin-css-modules pnpm

Imports

• styles
  wrong:

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

  correct:

  import styles from './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
  wrong:

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

  correct:

  import { myClass } 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
  wrong:

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

  correct:

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

  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.

Quickstart

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