{"id":21026203,"url":"https://github.com/mizdra/css-modules-kit","last_synced_at":"2026-02-07T16:06:05.924Z","repository":{"id":262808394,"uuid":"883025851","full_name":"mizdra/css-modules-kit","owner":"mizdra","description":"A toolkit for making CSS Modules useful.","archived":false,"fork":false,"pushed_at":"2025-04-29T11:11:08.000Z","size":1089,"stargazers_count":46,"open_issues_count":14,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-07T22:51:13.637Z","etag":null,"topics":["css-modules","typescript-language-server-plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mizdra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"mizdra"}},"created_at":"2024-11-04T08:50:02.000Z","updated_at":"2025-05-06T07:11:02.000Z","dependencies_parsed_at":"2024-12-29T05:18:32.656Z","dependency_job_id":"da66a634-7748-4260-a882-e1d30dd79a7a","html_url":"https://github.com/mizdra/css-modules-kit","commit_stats":null,"previous_names":["mizdra/honey-css-modules","mizdra/css-modules-kit"],"tags_count":29,"template":false,"template_full_name":"mizdra/npm-package-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizdra%2Fcss-modules-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizdra%2Fcss-modules-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizdra%2Fcss-modules-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizdra%2Fcss-modules-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mizdra","download_url":"https://codeload.github.com/mizdra/css-modules-kit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254322847,"owners_count":22051677,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css-modules","typescript-language-server-plugin"],"created_at":"2024-11-19T11:43:39.981Z","updated_at":"2026-02-07T16:06:05.912Z","avatar_url":"https://github.com/mizdra.png","language":"TypeScript","funding_links":["https://github.com/sponsors/mizdra"],"categories":["⭐ Top Extensions"],"sub_categories":[],"readme":"# CSS Modules Kit\n\nA toolkit for making CSS Modules useful.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Logo\" width=\"256\" height=\"256\" src=\"./docs/logo.png\" /\u003e\n\u003c/p\u003e\n\n## Intro\n\nBy default, CSS Modules have limited language features in editors. For example:\n\n- Clicking on `styles.button` does not \"Go to Definition\" in `Button.module.css`.\n- Renaming `styles.button` modifies the code in `Button.tsx` but not in `Button.module.css`.\n- Performing \"Find All References\" for `styles.button` finds references in `Button.tsx`, not in `Button.module.css`.\n\nIt 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.\n\nCSS 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.\n\nIn 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.\n\n## Get Started\n\nSee [docs/get-started.md](./docs/get-started.md).\n\n## Playground\n\n1. Open https://stackblitz.com/~/github.com/mizdra/css-modules-kit-example\n2. 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.\n3. Open `src/a.tsx`. CSS Modules language features should now be enabled.\n\n## Available Tools\n\n- [`@css-modules-kit/ts-plugin`](./packages/ts-plugin/README.md)\n- [`@css-modules-kit/codegen`](./packages/codegen/README.md)\n- [`@css-modules-kit/stylelint-plugin`](./packages/stylelint-plugin/README.md)\n- [`@css-modules-kit/eslint-plugin`](./packages/eslint-plugin/README.md)\n\n## Supported Language Features\n\n\u003cdetails\u003e\n\u003csummary\u003eGo to Definition\u003c/summary\u003e\n\nhttps://github.com/user-attachments/assets/bdeb2c8a-d615-4223-bae4-e7446f62d353\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRename Symbol\u003c/summary\u003e\n\nhttps://github.com/user-attachments/assets/db39a95e-2fc8-42a6-a64d-02f2822afbfe\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFind All References\u003c/summary\u003e\n\nhttps://github.com/user-attachments/assets/df1e2feb-2a1a-4bf5-ae70-1cac36d90409\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDefinition Preview by Hover\u003c/summary\u003e\n\nYou can preview the definition with \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eHover\u003c/kbd\u003e on macOS and VS Code (key bindings may vary depending on your OS and editor).\n\nhttps://github.com/user-attachments/assets/8d42acb8-2822-4fe6-89ce-8472c7065b8b\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAutomatically update import statements when moving `*.module.css`\u003c/summary\u003e\n\nhttps://github.com/user-attachments/assets/4af168fa-357d-44e1-b010-3053802bf1a2\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCreate CSS Module file for current file\u003c/summary\u003e\n\nIf there is no CSS Module file corresponding to `xxx.tsx`, create one.\n\nhttps://github.com/user-attachments/assets/05f9e839-9617-43dc-a519-d5a20adf1146\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eComplete `className={...}` instead of `className=\"...\"`\u003c/summary\u003e\n\nIn 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.\n\nTherefore, instead of completing `className=\"...\"`, it should complete `className={...}`.\n\nhttps://github.com/user-attachments/assets/b3609c8a-123f-4f4b-af8c-3c8bf7ab4363\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ePrioritize the `styles' import for the current component file\u003c/summary\u003e\n\nWhen 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.\n\nSo I have made it so that the `styles` of the CSS Module file corresponding to the current file is shown first.\n\n\u003cimg width=\"821\" alt=\"image\" src=\"https://github.com/user-attachments/assets/413373ec-1258-484d-9248-bc173e4f6d4a\" /\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAdd missing CSS rule\u003c/summary\u003e\n\nIf you are trying to use a class name that is not defined, you can add it with Quick Fixes.\n\nhttps://github.com/user-attachments/assets/3502150a-985d-45f3-9912-bbc183e41c03\n\n\u003c/details\u003e\n\n## Configuration\n\ncss-modules-kit uses `tsconfig.json` as its configuration file. This configuration only affects the ts-plugin and codegen.\n\n### `cmkOptions.enabled`\n\nType: `boolean`, Default: `true`\n\nEnables or disables css-modules-kit. When set to `false`, codegen will exit with an error. Currently, both codegen and the ts-plugin will work even if this option is omitted, but in the future, they will not work unless this option is set to `true`. For more details, see [#289](https://github.com/mizdra/css-modules-kit/issues/289).\n\n```jsonc\n{\n  \"compilerOptions\": {\n    // ...\n  },\n  \"cmkOptions\": {\n    \"enabled\": true,\n  },\n}\n```\n\n### `cmkOptions.dtsOutDir`\n\nType: `string`, Default: `\"generated\"`\n\nSpecifies the directory where `*.d.ts` files are output.\n\n```jsonc\n{\n  \"compilerOptions\": {\n    // ...\n  },\n  \"cmkOptions\": {\n    \"dtsOutDir\": \"generated/cmk\",\n  },\n}\n```\n\n### `cmkOptions.arbitraryExtensions`\n\nType: `boolean`, Default: `false`\n\nDetermines whether to generate `*.module.d.css.ts` instead of `*.module.css.d.ts`.\n\n```jsonc\n{\n  \"compilerOptions\": {\n    // ...\n  },\n  \"cmkOptions\": {\n    \"arbitraryExtensions\": true,\n  },\n}\n```\n\n### `cmkOptions.namedExports`\n\nType: `boolean`, Default: `false`\n\nDetermines whether to generate named exports in the d.ts file instead of a default export.\n\n```jsonc\n{\n  \"compilerOptions\": {\n    // ...\n  },\n  \"cmkOptions\": {\n    \"namedExports\": true,\n  },\n}\n```\n\n### `cmkOptions.prioritizeNamedImports`\n\nType: `boolean`, Default: `false`\n\nWhether to prioritize named imports over namespace imports when adding import statements. This option only takes effect when `cmkOptions.namedExports` is `true`.\n\nWhen this option is `true`, `import { button } from '...'` will be added. When this option is `false`, `import button from '...'` will be added.\n\n```jsonc\n{\n  \"compilerOptions\": {\n    // ...\n  },\n  \"cmkOptions\": {\n    \"namedExports\": true,\n    \"prioritizeNamedImports\": true,\n  },\n}\n```\n\n### `cmkOptions.keyframes`\n\nType: `boolean`, Default: `true`\n\nDetermines whether to generate the [token](docs/glossary.md#token) of keyframes in the d.ts file.\n\n```jsonc\n{\n  \"compilerOptions\": {\n    // ...\n  },\n  \"cmkOptions\": {\n    \"keyframes\": false,\n  },\n}\n```\n\n## Limitations\n\nDue to implementation constraints and technical reasons, css-modules-kit has various limitations.\n\n- Sass and Less are not supported.\n  - 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.\n- Case conversion for [token](docs/glossary.md#token) names is not supported.\n  - For example, if you have a CSS class `.foo-bar`, it will be exported as `styles['foo-bar']`, not `styles.fooBar` or `styles.foo_bar`.\n- The [token](docs/glossary.md#token) names must be valid JavaScript identifiers when `cmkOptions.namedExports` is `true`.\n  - For example, `.fooBar` and `.foo_bar` are supported, but `.foo-bar` is not supported.\n  - This restriction may be lifted in the future.\n- The specifiers in `@import '\u003cspecifier\u003e'` and `@value ... from '\u003cspecifier\u003e'` are resolved according to TypeScript's module resolution method.\n  - This may differ from the resolution methods of bundlers like Turbopack or Vite.\n  - 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`.\n    - Example: `\"paths\": { \"@/*\": [\"src/*\"] }`\n  - If you want to omit `.css`, use [`compilerOptions.moduleSuffixes`](https://www.typescriptlang.org/tsconfig/#moduleSuffixes).\n    - Example: `\"moduleSuffixes\": [\".css\", \"\"]`\n  - If you want to resolve the `style` condition, use [`compilerOptions.customConditions`](https://www.typescriptlang.org/tsconfig/#customConditions).\n    - Example: `\"customConditions\": [\"style\"]`\n- `:local .foo {...}` is not supported.\n  - Use `:local(.foo) {...}` instead.\n- `:global .foo {...}` is not supported.\n  - Use `:global(.foo) {...}` instead.\n- `@keyframes :local(foo) {...}` is not supported.\n  - Use `@keyframes foo {...}` instead.\n  - Meanwhile, `@keyframes :global(foo) { ... }` is supported.\n- VS Code for Web is not supported.\n\n## Comparison\n\n### [Viijay-Kr/react-ts-css](https://github.com/Viijay-Kr/react-ts-css)\n\nViijay-Kr/react-ts-css also provides rich language features for CSS Modules. However, it is implemented using the VS Code Extension API. Therefore, it only supports VS Code.\n\nOn the other hand, css-modules-kit is implemented using the TypeScript Language Service Plugin. It is a technology that does not depend on the editor. css-modules-kit supports editors other than VS Code.\n\n### [mrmckeb/typescript-plugin-css-modules](https://github.com/mrmckeb/typescript-plugin-css-modules)\n\nmrmckeb/typescript-plugin-css-modules is also implemented using the TypeScript Language Service Plugin. However, it only supports basic language features such as completion, typed `styles`, and Go to Definition. Cross-file language features between `*.tsx` and `.module.css`—such as Rename and Find All References—are not supported.\n\nThis is because mrmckeb/typescript-plugin-css-modules does not extend tsserver to handle `*.module.css` files. Due to the lack of information about `*.module.css` files, tsserver cannot provide cross-file language features between `*.tsx` and `.module.css`.\n\nOn the other hand, css-modules-kit extends tsserver to handle `*.module.css` files. The extension is realized by [Volar.js](https://volarjs.dev/). Please read the following slides for details (in Japanese).\n\n- https://speakerdeck.com/mizdra/css-modules-kit\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizdra%2Fcss-modules-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmizdra%2Fcss-modules-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizdra%2Fcss-modules-kit/lists"}