CSS Modules Kit

A toolkit for making CSS Modules useful.

Intro

By default, CSS Modules have limited language features in editors. For example:

• Clicking on styles.button does not jump to its definition in Button.module.css.
• When renaming styles.button, the corresponding .button {...} in Button.module.css is not renamed.
• Performing "Find All References" on styles.button does not find its definition in Button.module.css.

It has been difficult to solve these issues because the TypeScript Language Server (tsserver) does not handle CSS files. Since tsserver does not hold information about CSS files, it cannot calculate jump destinations or determine which code should be renamed.

css-modules-kit addresses this by using a TypeScript Language Service Plugin. With this plugin, css-modules-kit extends tsserver to handle *.module.css files. As a result, many language features like code navigation and rename refactoring become available.

Additionally, css-modules-kit provides various development tools for CSS Modules, such as a stylelint plugin and a utility for generating *.d.ts files.

Supported Language Features

Go to Definition

2024-12-22.2.05.16.mov

Rename class names or `@value`

2024-12-22.2.13.35.mov

Find all references

2024-12-22.2.10.01.mov

Automatically update import statements when moving `*.module.css`

2024-12-26.20.24.48.mov

Create CSS Module file for current file.

If there is no CSS Module file corresponding to xxx.tsx, create one.

2025-02-02.19.07.06.mov

Complete `className={...}` instead of `className="..."`

In projects where CSS Modules are used, the element is styled with className={styles.xxx}. However, when you type className, className="..." is completed. This is annoying to the user.

So, instead of className="..." instead of className={...} instead of className="...".

2025-02-02.19.07.27.mov

Prioritize the `styles' import for the current component file

When you request styles completion, the CSS Module file styles will be suggested. If there are many CSS Module files in the project, more items will be suggested. This can be confusing to the user.

So I have made it so that the styles of the CSS Module file corresponding to the current file is shown first.

Add missing CSS rule

If you are trying to use a class name that is not defined, you can add it with Quick Fixes.

2025-02-02.19.24.36.mov

Get Started

Please read the Get Started guide.

How to try demo

1. Open this repository with VS Code
2. Open Run and Debug menu
3. Select vscode: debug configuration and start debugging

Configuration

css-modules-kit uses tsconfig.json as its configuration file.

include/exclude

In TypeScript, the include/exclude properties specify which *.ts files to compile. css-modules-kit reuses these options to determine which *.module.css files to handle with codegen and ts-plugin. Therefore, make sure your *.module.css files are included in the include or exclude settings.

{
  // For example, if your project's `*.module.css` files are in `src/`:
  "include": ["src"], // Default is ["**/*"], so it can be omitted
  "compilerOptions": {
    // ...
  },
}

cmkOptions.dtsOutDir

Specifies the directory where *.d.ts files are output. The default is "generated".

{
  "compilerOptions": {
    // ...
  },
  "cmkOptions": {
    "dtsOutDir": "generated/cmk",
  },
}

cmkOptions.arbitraryExtensions

Determines whether to generate *.module.d.css.ts instead of *.module.css.d.ts. The default is false.

{
  "compilerOptions": {
    // ...
  },
  "cmkOptions": {
    "arbitraryExtensions": true,
  },
}

Limitations

• Sass/Less are not supported to simplify the implementation
• :local .foo {...} (without any arguments) is not supported to simplify the implementation
• :global .foo {...} (without any arguments) is not supported to simplify the implementation
• Some editors do not allow rename from *.module.css
  • See #121 for more details.
• css-modules-kit does not work on VS Code for Web
  • This is to simplify implementation.

History of this project

This project was created as a next-generation tool to replace happy-css-modules

happy-css-modules was also a tool that provided language functionality for *.module.css. However, the tool was limited in the type of language features it could provide. To solve this limitation, css-modules-kit was created.