Skip to content

get-started.md

Latest commit

 

History

History
94 lines (67 loc) · 3.74 KB

get-started.md

File metadata and controls

94 lines (67 loc) · 3.74 KB

Get Started

CSS Modules Kit consists of the following three tools:

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

ts-plugin is a TypeScript Language Service Plugin for CSS Modules. Installing ts-plugin enables various language features (see Supported Language Features).

Installation steps differ depending on your editor. Follow the setup guide below:

Install codegen

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

npm i -D @css-modules-kit/codegen

Configure npm-scripts to run the cmk command before building and type checking. Optionally, configure the cmk --watch command for debug builds.

{
  "scripts": {
    "generate": "cmk",
    "build": "run-s -c generate build:*",
    "build:vite": "vite build",
    "dev": "run-p dev:*",
    "dev:cmk": "cmk --watch",
    "dev:vite": "vite",
    "lint": "run-s -c generate lint:*",
    "lint:eslint": "eslint .",
    "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 option.

Configure tsconfig.json

To enable tsserver and tsc to load type definitions generated by CSS Modules Kit, you need to set up tsconfig.json.

  • Set the cmkOptions.enabled option to true
  • Make sure the include option includes *.module.css files
    • ✅ Good cases:
      • Omit include (equivalent to ["**/*"])
      • ["src"] (equivalent to ["src/**/*"])
      • ["src/**/*"]
    • ❌ Bad cases:
      • ["src/**/*.ts"]
      • ["src/index.ts"]
  • Set the rootDirs option to include both the directory containing tsconfig.json and the generated directory.
    • Example: [".", "generated"]

Below is an example configuration:

{
  "compilerOptions": {
    "rootDirs": [".", "generated"],
    // ...
  },
  "cmkOptions": {
    "enabled": true,
  },
}

Install linter-plugin

The linter-plugin is a linter plugin for *.module.css files. Currently, we support the following linters:

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)

The behavior of ts-plugin and codegen can be customized using the cmkOptions option in tsconfig.json. For details, see Configuration.