diff --git a/.changeset/tame-houses-taste.md b/.changeset/tame-houses-taste.md new file mode 100644 index 00000000..339a84a0 --- /dev/null +++ b/.changeset/tame-houses-taste.md @@ -0,0 +1,8 @@ +--- +'@css-modules-kit/ts-plugin': patch +'@css-modules-kit/codegen': patch +'css-modules-kit-vscode': patch +'css-modules-kit-zed': patch +--- + +docs: update documentation diff --git a/README.md b/README.md index a659a918..6f9453e4 100644 --- a/README.md +++ b/README.md @@ -10,15 +10,32 @@ A toolkit for making CSS Modules useful. By default, CSS Modules have limited language features in editors. For example: -- Clicking on `styles.button` does not go to its definition in `Button.module.css`. -- Renaming `styles.button` does not rename the corresponding `.button {...}` in `Button.module.css`. -- Find all references of `styles.button` does not include its definition in `Button.module.css`. +- Clicking on `styles.button` does not "Go to Definition" in `Button.module.css`. +- Renaming `styles.button` modifies the code in `Button.tsx` but not in `Button.module.css`. +- Performing "Find All References" for `styles.button` finds references in `Button.tsx`, not 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 load CSS files, it cannot determine which definitions to go to or which code to rename. +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. -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. +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. -css-modules-kit also provides various development tools for CSS Modules. For example, stylelint plugins and the tool that generates `*.d.ts` files. +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. + +## Get Started + +See [docs/get-started.md](./docs/get-started.md). + +## Playground + +1. Open https://stackblitz.com/~/github.com/mizdra/css-modules-kit-example +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. +3. Open `src/a.tsx`. CSS Modules language features should now be enabled. + +## Available Tools + +- [`@css-modules-kit/ts-plugin`](./packages/ts-plugin/README.md) +- [`@css-modules-kit/codegen`](./packages/codegen/README.md) +- [`@css-modules-kit/stylelint-plugin`](./packages/stylelint-plugin/README.md) +- [`@css-modules-kit/eslint-plugin`](./packages/eslint-plugin/README.md) ## Supported Language Features @@ -37,7 +54,7 @@ https://github.com/user-attachments/assets/db39a95e-2fc8-42a6-a64d-02f2822afbfe
-Find all references +Find All References https://github.com/user-attachments/assets/df1e2feb-2a1a-4bf5-ae70-1cac36d90409 @@ -73,7 +90,7 @@ https://github.com/user-attachments/assets/05f9e839-9617-43dc-a519-d5a20adf1146 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="..."`. +Therefore, instead of completing `className="..."`, it should complete `className={...}`. https://github.com/user-attachments/assets/b3609c8a-123f-4f4b-af8c-3c8bf7ab4363 @@ -99,33 +116,9 @@ https://github.com/user-attachments/assets/3502150a-985d-45f3-9912-bbc183e41c03
-## Get Started - -Please read the [Get Started](docs/get-started.md) guide. - -## How to try demo - -1. Open this repository with VS Code -2. Open `Run and Debug` menu -3. Select `vscode (1-basic)` 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. - -```jsonc -{ - // For example, if your project's `*.module.css` files are in `src/`: - "include": ["src"], // Default is ["**/*"], so it can be omitted - "compilerOptions": { - // ... - }, -} -``` +css-modules-kit uses `tsconfig.json` as its configuration file. This configuration only affects the ts-plugin and codegen. ### `cmkOptions.enabled` @@ -232,23 +225,23 @@ Determines whether to generate the [token](docs/glossary.md#token) of keyframes } ``` -## Supported CSS Modules features - -- `:local(...)` and `:global(...)` -- `@keyframes { ... }` -- `@value : ;` -- `@value [, ]+ from ;` -- `@import ;` - ## Limitations -To simplify the implementation, some features are not supported. +Due to implementation constraints and technical reasons, css-modules-kit has various limitations. - Sass and Less are not supported. - 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. - The name of classes, `@value`, and `@keyframes` must be valid JavaScript identifiers. - For example, `.fooBar` and `.foo_bar` are supported, but `.foo-bar` is not supported. - See [#176](https://github.com/mizdra/css-modules-kit/issues/176) for more details. +- The specifiers in `@import ''` and `@value ... from ''` are resolved according to TypeScript's module resolution method. + - This may differ from the resolution methods of bundlers like Turbopack or Vite. + - 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`. + - Example: `"paths": { "@/*": ["src/*"] }` + - If you want to omit `.css`, use [`compilerOptions.moduleSuffixes`](https://www.typescriptlang.org/tsconfig/#moduleSuffixes). + - Example: `"moduleSuffixes": [".css", ""]` + - If you want to resolve the `style` condition, use [`compilerOptions.customConditions`](https://www.typescriptlang.org/tsconfig/#customConditions). + - Example: `"customConditions": ["style"]` - `:local .foo {...}` is not supported. - Use `:local(.foo) {...}` instead. - `:global .foo {...}` is not supported. diff --git a/crates/zed/README.md b/crates/zed/README.md index 87596cf7..79a4b500 100644 --- a/crates/zed/README.md +++ b/crates/zed/README.md @@ -4,15 +4,4 @@ The Zed extension for CSS Modules Kit ## Installation -1. Install "CSS Modules Kit" extension on Zed. -2. Add the following to your `~./config/zed/settings.json` file: - ```json - { - "languages": { - "CSS": { - "language_servers": ["vtsls", "..."] - } - } - } - ``` -3. Restart Zed. +See [Get Started](https://github.com/mizdra/css-modules-kit/tree/main/packages/ts-plugin#zed). diff --git a/docs/get-started.md b/docs/get-started.md index f41062b7..eff42a12 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -1,27 +1,28 @@ # Get Started +CSS Modules Kit consists of the following three tools: + +- ts-plugin ([`@css-modules-kit/ts-plugin`](../packages/ts-plugin/README.md)) +- codegen ([`@css-modules-kit/codegen`](../packages/codegen/README.md)) +- linter-plugin ([`@css-modules-kit/stylelint-plugin`](../packages/stylelint-plugin/README.md) or [`@css-modules-kit/eslint-plugin`](../packages/eslint-plugin/README.md)) + +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. + +This guide explains each tool and how to set it up. + ## Install ts-plugin -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. - -- For VS Code: - - Install the [CSS Modules Kit extension](https://marketplace.visualstudio.com/items?itemName=mizdra.css-modules-kit-vscode) -- For Neovim: - - Install [`@css-modules-kit/ts-plugin`](../packages/ts-plugin/README.md#installation) and [set up the configuration](../packages/ts-plugin/README.md) -- For Emacs: - - Not yet supported -- For Zed: - - See [crates/zed/README.md](../crates/zed/README.md) -- For WebStorm: - - Not yet supported -- For StackBlitz Codeflow: - - Install the [CSS Modules Kit extension](https://open-vsx.org/extension/mizdra/css-modules-kit-vscode) +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)). + +Installation steps differ depending on your editor. Follow the setup guide below: + +- [Installation](../packages/ts-plugin/README.md#installation) ## Install codegen -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. +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 type checking in the terminal. -To ensure `tsc` properly type-checks, you need to generate `*.module.css.d.ts` files. This is handled by codegen. +To achieve the expected type checking in the terminal, `.module.css.d.ts` files are required. codegen is a tool that generates these files. To install codegen, run the following command: @@ -29,35 +30,40 @@ To install codegen, run the following command: npm i -D @css-modules-kit/codegen ``` -Configure npm-script to run `cmk` command before building and type checking. This command generates `*.module.css.d.ts` files in `generated` directory. +Configure npm-scripts to run the `cmk` command before building and type checking. Optionally, configure the `cmk --watch` command for debug builds. ```json { "scripts": { - "gen": "cmk", - "build": "run-s -c gen build:*", + "generate": "cmk", + "build": "run-s -c generate build:*", "build:vite": "vite build", - "lint": "run-s -c gen lint:*", + "dev": "run-p dev:*", + "dev:cmk": "cmk --watch", + "dev:vite": "vite", + "lint": "run-s -c generate lint:*", "lint:eslint": "eslint .", - "lint:tsc": "tsc --noEmit", - "lint:prettier": "prettier --check ." + "lint:tsc": "tsc --noEmit" } } ``` +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. + ## Configure `tsconfig.json` -Finally, you need to configure your tsconfig.json so that css-modules-kit works correctly. +To enable tsserver and `tsc` to load type definitions generated by CSS Modules Kit, you need to set up `tsconfig.json`. -- Set `cmkOptions.enabled` to `true` to enable css-modules-kit. -- Omit the `include` options or ensure that `*.module.css` files are included when specifying them explicitly. +- Set the [`cmkOptions.enabled`](../README.md#cmkoptionsenabled) option to `true` +- Make sure the [`include`](https://www.typescriptlang.org/tsconfig/#include) option includes `*.module.css` files - ✅ Good cases: - Omit `include` (equivalent to `["**/*"]`) - - Use patterns like `["src"]`, `["src/**/*"]` + - `["src"]` (equivalent to `["src/**/*"]`) + - `["src/**/*"]` - ❌ Bad cases: - `["src/**/*.ts"]` - - `["src/index.ts"]` (excludes `*.module.css` files) -- Set the `rootDirs` option to include both the directory containing `tsconfig.json` and the `generated` directory. + - `["src/index.ts"]` +- Set the [`rootDirs`](https://www.typescriptlang.org/tsconfig/#rootDirs) option to include both the directory containing `tsconfig.json` and the `generated` directory. - Example: `[".", "generated"]` Below is an example configuration: @@ -74,15 +80,15 @@ Below is an example configuration: } ``` -## Install linter plugin (Optional) +## Install linter-plugin -We provide linter plugin for CSS Modules. Currently, we support the following linters: +The linter-plugin is a linter plugin for `*.module.css` files. Currently, we support the following linters: - [stylelint-plugin](../packages/stylelint-plugin/README.md) - [eslint-plugin](../packages/eslint-plugin/README.md) -All linter plugins offer the same set of rules. So please choose and install one. +All linter plugins provide the same set of rules—choose and install whichever you prefer. For installation instructions, refer to their README files. ## Customization (Optional) -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). +The behavior of ts-plugin and codegen can be customized using the `cmkOptions` option in `tsconfig.json`. For details, see [Configuration](../README.md#configuration). diff --git a/packages/codegen/README.md b/packages/codegen/README.md index 5146ae3e..e5dc838b 100644 --- a/packages/codegen/README.md +++ b/packages/codegen/README.md @@ -8,21 +8,6 @@ A tool for generating `*.d.ts` files for `*.module.css`. npm i -D @css-modules-kit/codegen ``` -## Requirements - -Set `cmkOptions.dtsOutDir` and `"."` to `rootDirs`. This is necessary for the `tsc` command to load the generated `*.d.ts` files. - -```json -{ - "compilerOptions": { - "rootDirs": [".", "generated"] // Required - }, - "cmkOptions": { - "dtsOutDir": "generated" // Default is `"generated"`, so it can be omitted - } -} -``` - ## Usage From the command line, run the `cmk` command. diff --git a/packages/ts-plugin/README.md b/packages/ts-plugin/README.md index 340971d7..565fef0a 100644 --- a/packages/ts-plugin/README.md +++ b/packages/ts-plugin/README.md @@ -1,37 +1,70 @@ # `@css-modules-kit/ts-plugin` -A TypeScript Language Service Plugin for CSS Modules +A TypeScript Language Service Plugin for CSS Modules. -## What is this? +## Installation -`@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. +### VS Code -## Installation +Install the ts-plugin via the Extension. Please install: + +- https://marketplace.visualstudio.com/items?itemName=mizdra.css-modules-kit-vscode + +### Neovim + +First, install ts-plugin globally. ```bash -npm i -D @css-modules-kit/ts-plugin +npm i -g @css-modules-kit/ts-plugin ``` -## How to setup your editor - -### Neovim +Next, update your LSP client configuration. Below is an example using `nvim-lspconfig`. ```lua local lspconfig = require('lspconfig') -lspconfig.ts_ls.setup { - init_options = { - plugins = { - { - name = '@css-modules-kit/ts-plugin', - languages = { 'css' }, - }, - }, - }, - filetypes = { 'typescript', 'javascript', 'javascriptreact', 'typescriptreact', 'css' }, -} +-- TODO: Welcome to contribute ``` +### Emacs + +First, install ts-plugin globally. + +```bash +npm i -g @css-modules-kit/ts-plugin +``` + +Next, update your LSP client configuration. + +TODO: Welcome to contribute + +### Zed + +Install the ts-plugin via the Extension. Please follow the steps below: + +1. Install ["CSS Modules Kit" extension](https://zed.dev/extensions/css-modules-kit). +2. Add the following to your `~./config/zed/settings.json` file: + ```json + { + "languages": { + "CSS": { + "language_servers": ["vtsls", "..."] + } + } + } + ``` +3. Restart Zed. + +### WebStorm + +Not yet supported. + +### StackBlitz Codeflow + +Install the ts-plugin via the Extension. Please install: + +- https://open-vsx.org/extension/mizdra/css-modules-kit-vscode + ## Configuration -See [css-modules-kit's README](https://github.com/mizdra/css-modules-kit?tab=readme-ov-file#configuration). +See [Configuration](https://github.com/mizdra/css-modules-kit?tab=readme-ov-file#configuration). diff --git a/packages/vscode/README.md b/packages/vscode/README.md index 15b60ef2..900fe897 100644 --- a/packages/vscode/README.md +++ b/packages/vscode/README.md @@ -1,7 +1,7 @@ # css-modules-kit-vscode -The VS Code extension for CSS Modules +The VS Code extension for CSS Modules. -## What is this? +## Installation -This is an extension for using `@css-modules-kit/ts-plugin` in VS Code. +See [Get Started](https://github.com/mizdra/css-modules-kit/tree/main/packages/ts-plugin#vs-code).