You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+35-42Lines changed: 35 additions & 42 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,15 +10,32 @@ A toolkit for making CSS Modules useful.
10
10
11
11
By default, CSS Modules have limited language features in editors. For example:
12
12
13
-
- Clicking on `styles.button` does not go to its definition in `Button.module.css`.
14
-
- Renaming `styles.button`does not rename the corresponding `.button {...}` in `Button.module.css`.
15
-
- Find all references of`styles.button`does not include its definition in `Button.module.css`.
13
+
- Clicking on `styles.button` does not "Go to Definition" in `Button.module.css`.
14
+
- Renaming `styles.button`modifies the code in `Button.tsx` but not in `Button.module.css`.
15
+
-Performing "Find All References" for`styles.button`finds references in `Button.tsx`, not in `Button.module.css`.
16
16
17
-
It has been difficult to solve these issues because the TypeScript Language Server (tsserver) does not handle CSS files. Since tsserver does not load CSS files, it cannot determine which definitions to go to or which code to rename.
17
+
It has been difficult to solve these issues because the TypeScript Language Server (tsserver) does not load CSS files. TSServer does not know which part of the code to "Go to Definition" for, nor which part of the code to rename.
18
18
19
-
css-modules-kit solves this problem by using the [TypeScript Language Service Plugin](https://github.com/microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin). css-modules-kit extends tsserver to handle`*.module.css` files using it. As a result, rich language features like code navigation and rename refactoring become available. Moreover, it works with various editors.
19
+
CSS Modules Kit solves this problem by using the [TypeScript Language Service Plugin](https://github.com/microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin) and [Volar.js](https://volarjs.dev/). They extend tsserver to load`*.module.css` files. As a result, [rich language features](#supported-language-features) become available. Moreover, it works with various editors.
20
20
21
-
css-modules-kit also provides various development tools for CSS Modules. For example, stylelint plugins and the tool that generates `*.d.ts` files.
21
+
In addition, CSS Modules Kit provides various tools for CSS Modules (e.g., codegen, linter-plugin). CSS Modules Kit provides you everything you need. It saves you from the hassle of combining multiple third-party tools.
22
+
23
+
## Get Started
24
+
25
+
See [docs/get-started.md](./docs/get-started.md).
26
+
27
+
## Playground
28
+
29
+
1. Open https://stackblitz.com/~/github.com/mizdra/css-modules-kit-example
30
+
2. After waiting a moment, a message will appear in the bottom-right saying `you want to install the recommended extensions`. Click `Install` and wait for the installation to complete.
31
+
3. Open `src/a.tsx`. CSS Modules language features should now be enabled.
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.
75
92
76
-
So, instead of `className="..."` instead of `className={...}` instead of `className="..."`.
93
+
Therefore, instead of completing `className="..."`, it should complete `className={...}`.
Please read the [Get Started](docs/get-started.md) guide.
105
-
106
-
## How to try demo
107
-
108
-
1. Open this repository with VS Code
109
-
2. Open `Run and Debug` menu
110
-
3. Select `vscode (1-basic)` configuration and start debugging
111
-
112
119
## Configuration
113
120
114
-
css-modules-kit uses `tsconfig.json` as its configuration file.
115
-
116
-
### `include`/`exclude`
117
-
118
-
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.
119
-
120
-
```jsonc
121
-
{
122
-
// For example, if your project's `*.module.css` files are in `src/`:
123
-
"include": ["src"], // Default is ["**/*"], so it can be omitted
124
-
"compilerOptions": {
125
-
// ...
126
-
},
127
-
}
128
-
```
121
+
css-modules-kit uses `tsconfig.json` as its configuration file. This configuration only affects the ts-plugin and codegen.
129
122
130
123
### `cmkOptions.enabled`
131
124
@@ -232,23 +225,23 @@ Determines whether to generate the [token](docs/glossary.md#token) of keyframes
232
225
}
233
226
```
234
227
235
-
## Supported CSS Modules features
236
-
237
-
-`:local(...)` and `:global(...)`
238
-
-`@keyframes <name> { ... }`
239
-
-`@value <name>: <value>;`
240
-
-`@value <name>[, <value>]+ from <module-specifier>;`
241
-
-`@import <module-specifier>;`
242
-
243
228
## Limitations
244
229
245
-
To simplify the implementation, some features are not supported.
230
+
Due to implementation constraints and technical reasons, css-modules-kit has various limitations.
246
231
247
232
- Sass and Less are not supported.
248
233
- If you want to use Sass and Less, please use [happy-css-modules](https://github.com/mizdra/happy-css-modules). Although it does not offer as rich language features as css-modules-kit, it provides basic features such as code completion and Go to Definition.
249
234
- The name of classes, `@value`, and `@keyframes` must be valid JavaScript identifiers.
250
235
- For example, `.fooBar` and `.foo_bar` are supported, but `.foo-bar` is not supported.
251
236
- See [#176](https://github.com/mizdra/css-modules-kit/issues/176) for more details.
237
+
- The specifiers in `@import '<specifier>'` and `@value ... from '<specifier>'` are resolved according to TypeScript's module resolution method.
238
+
- This may differ from the resolution methods of bundlers like Turbopack or Vite.
239
+
- If you want to use import aliases, use [`compilerOptions.paths`](https://www.typescriptlang.org/tsconfig/#paths) or [`imports`](https://nodejs.org/api/packages.html#imports) in `package.json`.
240
+
- Example: `"paths": { "@/*": ["src/*"] }`
241
+
- If you want to omit `.css`, use [`compilerOptions.moduleSuffixes`](https://www.typescriptlang.org/tsconfig/#moduleSuffixes).
242
+
- Example: `"moduleSuffixes": [".css", ""]`
243
+
- If you want to resolve the `style` condition, use [`compilerOptions.customConditions`](https://www.typescriptlang.org/tsconfig/#customConditions).
- linter-plugin ([`@css-modules-kit/stylelint-plugin`](../packages/stylelint-plugin/README.md) or [`@css-modules-kit/eslint-plugin`](../packages/eslint-plugin/README.md))
8
+
9
+
Each tool is independent and can be used on its own. However, using all three together provides a better developer experience. At minimum, we recommend installing both ts-plugin and codegen.
10
+
11
+
This guide explains each tool and how to set it up.
12
+
3
13
## Install ts-plugin
4
14
5
-
To enable CSS Modules language features in your editor, you need to install [`@css-modules-kit/ts-plugin`](../packages/ts-plugin/README.md) (ts-plugin). The installation method varies by editor.
6
-
7
-
- For VS Code:
8
-
- Install the [CSS Modules Kit extension](https://marketplace.visualstudio.com/items?itemName=mizdra.css-modules-kit-vscode)
9
-
- For Neovim:
10
-
- Install [`@css-modules-kit/ts-plugin`](../packages/ts-plugin/README.md#installation) and [set up the configuration](../packages/ts-plugin/README.md)
11
-
- For Emacs:
12
-
- Not yet supported
13
-
- For Zed:
14
-
- See [crates/zed/README.md](../crates/zed/README.md)
15
-
- For WebStorm:
16
-
- Not yet supported
17
-
- For StackBlitz Codeflow:
18
-
- Install the [CSS Modules Kit extension](https://open-vsx.org/extension/mizdra/css-modules-kit-vscode)
15
+
ts-plugin is a TypeScript Language Service Plugin for CSS Modules. Installing ts-plugin enables various language features (see [Supported Language Features](#supported-language-features)).
16
+
17
+
Installation steps differ depending on your editor. Follow the setup guide below:
The ts-plugin provides type definitions for `styles` as `{ foo: string, bar: string }`. However, these types are not applied during type-checking with the `tsc` command.
23
+
ts-plugin provides type definitions like `{ foo: string, bar: string }`for `styles`. However, ts-plugin only affects the behavior of the TypeScript Language Server (tsserver). It does not affect `tsc`. Therefore, while `styles` will have the type `{ foo: string, bar: string }` during type checking in the editor, this is not the case for typechecking in the terminal.
23
24
24
-
To ensure `tsc` properly type-checks, you need to generate `*.module.css.d.ts` files. This is handled by codegen.
25
+
To achieve the expected type checking in the terminal, `.module.css.d.ts` files are required. codegen is a tool that generates these files.
25
26
26
27
To install codegen, run the following command:
27
28
28
29
```bash
29
30
npm i -D @css-modules-kit/codegen
30
31
```
31
32
32
-
Configure npm-script to run `cmk` command before building and type checking. This command generates `*.module.css.d.ts` files in `generated` directory.
33
+
Configure npm-scripts to run the `cmk` command before building and type checking. Optionally, configure the `cmk --watch` command for debug builds.
33
34
34
35
```json
35
36
{
36
37
"scripts": {
37
-
"gen": "cmk",
38
-
"build": "run-s -c gen build:*",
38
+
"generate": "cmk",
39
+
"build": "run-s -c generate build:*",
39
40
"build:vite": "vite build",
40
-
"lint": "run-s -c gen lint:*",
41
+
"dev": "run-p dev:*",
42
+
"dev:cmk": "cmk --watch",
43
+
"dev:vite": "vite",
44
+
"lint": "run-s -c generate lint:*",
41
45
"lint:eslint": "eslint .",
42
-
"lint:tsc": "tsc --noEmit",
43
-
"lint:prettier": "prettier --check ."
46
+
"lint:tsc": "tsc --noEmit"
44
47
}
45
48
}
46
49
```
47
50
51
+
By default, `*.module.css.d.ts` files are generated within the `generated` directory. The destination directory can be changed by setting the [`cmkOptions.dtsOutDir`](../README.md#cmkoptionsdtsoutdir) option.
52
+
48
53
## Configure `tsconfig.json`
49
54
50
-
Finally, you need to configure your tsconfig.json so that css-modules-kit works correctly.
55
+
To enable tsserver and `tsc` to load type definitions generated by CSS Modules Kit, you need to set up `tsconfig.json`.
51
56
52
-
- Set `cmkOptions.enabled`to `true` to enable css-modules-kit.
53
-
-Omit the `include` options or ensure that `*.module.css` files are included when specifying them explicitly.
57
+
- Set the [`cmkOptions.enabled`](../README.md#cmkoptionsenabled) option to `true`
58
+
-Make sure the [`include`](https://www.typescriptlang.org/tsconfig/#include) option includes `*.module.css` files
- Set the `rootDirs` option to include both the directory containing `tsconfig.json` and the `generated` directory.
65
+
-`["src/index.ts"]`
66
+
- Set the [`rootDirs`](https://www.typescriptlang.org/tsconfig/#rootDirs) option to include both the directory containing `tsconfig.json` and the `generated` directory.
61
67
- Example: `[".", "generated"]`
62
68
63
69
Below is an example configuration:
@@ -74,15 +80,15 @@ Below is an example configuration:
74
80
}
75
81
```
76
82
77
-
## Install linterplugin (Optional)
83
+
## Install linter-plugin
78
84
79
-
We provide linter plugin for CSS Modules. Currently, we support the following linters:
85
+
The linter-plugin is a linter plugin for `*.module.css` files. Currently, we support the following linters:
All linter plugins offer the same set of rules. So please choose and install one.
90
+
All linter plugins provide the same set of rules—choose and install whichever you prefer. For installation instructions, refer to their README files.
85
91
86
92
## Customization (Optional)
87
93
88
-
You can customize the behavior of codegen by adding the `cmkOptions` option to your `tsconfig.json`. For more details, please refer to[Configuration](../README.md#configuration).
94
+
The behavior of ts-plugin and codegen can be customized using the `cmkOptions` option in `tsconfig.json`. For details, see[Configuration](../README.md#configuration).
A TypeScript Language Service Plugin for CSS Modules
3
+
A TypeScript Language Service Plugin for CSS Modules.
4
4
5
-
## What is this?
5
+
## Installation
6
6
7
-
`@css-modules-kit/ts-plugin` is a TypeScript Language Service Plugin that extends tsserver to handle `*.module.css` files. As a result, many language features like code navigation and rename refactoring become available.
7
+
### VS Code
8
8
9
-
## Installation
9
+
Install the ts-plugin via the Extension. Please install:
0 commit comments