css-modules-lint

1.0.3 verified Fri May 01 auth: no javascript

Lint, autocomplete, and generate types for CSS Modules. Version 1.0.3 runs on Node >=20 and supports TypeScript, Vite, and ESLint. Includes a TypeScript Language Service Plugin for real-time diagnostics, Vite plugin for automatic .d.ts generation, and an ESLint plugin with undefined/unused class rules. Differentiators include unified tooling for both type generation and linting, CLI for CI integration, and support for SCSS, CSS, and Less modules.

Common errors

error Error: Cannot find module 'css-modules-lint/eslint' ↓

cause Using CommonJS require() instead of ESM import

fix

Use import statement: import cssModulesLint from 'css-modules-lint/eslint'; and ensure package.json has "type": "module" or file extension .mjs.

error Cannot start TypeScript LSP: No registered language service plugin 'css-modules-lint' ↓

cause Plugin name not correctly specified in tsconfig.json

fix

Ensure tsconfig.json has: "plugins": [{ "name": "css-modules-lint" }] (not 'css-modules-lint/typescript' or other paths).

error Parsing error: The keyword 'import' is reserved ↓

cause ESLint config still using legacy .eslintrc format but package requires flat config

fix

Upgrade to ESLint >=9 and use eslint.config.js with import syntax.

error TypeError: cssModulesDts is not a function ↓

cause Importing named export instead of default from 'css-modules-lint/vite'

fix

Change import to: import cssModulesDts from 'css-modules-lint/vite'; (not named import).

Warnings

breaking Peer dependencies: requires Node >=20, TypeScript >=5, ESLint >=9, and Vite >=4 ↓

fix Update Node, TypeScript, ESLint, or Vite to the required versions.

breaking ESLint plugin uses flat config only (ESLint >=9) and ESM imports ↓

fix Migrate ESLint config to flat config and use ESM imports (e.g., import cssModulesLint from 'css-modules-lint/eslint').

gotcha TypeScript plugin must be configured in tsconfig.json and editor's TypeScript language server must be restarted for changes to take effect ↓

fix After adding plugin to tsconfig.json, reload the TypeScript language server (e.g., VS Code: Ctrl+Shift+P -> TypeScript: Reload Project).

deprecated CLI 'generate' command for .d.ts generation is superseded by Vite plugin for development workflows ↓

fix Prefer using the Vite plugin cssModulesDts() for automatic generation during dev/build; CLI generate is still valid for CI.

gotcha Generated .d.ts files should be gitignored to avoid conflicts; they are regenerated by Vite plugin or CLI ↓

fix Add *.module.scss.d.ts, *.module.css.d.ts, *.module.less.d.ts to .gitignore.

Install

npm install css-modules-lint

yarn add css-modules-lint

pnpm add css-modules-lint

Imports

cssModulesLint (ESLint plugin)

wrong

const cssModulesLint = require('css-modules-lint/eslint')

correct

import cssModulesLint from 'css-modules-lint/eslint'

ESM-only; ESLint >=9 flat config required

cssModulesDts (Vite plugin)

wrong

import { cssModulesDts } from 'css-modules-lint/vite'

correct

import cssModulesDts from 'css-modules-lint/vite'

Default export from 'css-modules-lint/vite', not named

TypeScript plugin

wrong

{ "plugins": [{ "name": "css-modules-lint/typescript" }] }

correct

{ "plugins": [{ "name": "css-modules-lint" }] }

Not a JS import; configured in tsconfig.json

Quickstart

Full setup with init command, manual configurations for TypeScript, Vite, ESLint, .gitignore, and CI script.

// Install
npm install -D css-modules-lint

// Automatic setup
npx css-modules-lint init

// Or manual setup:
// 1. tsconfig.json
{
  "compilerOptions": {
    "plugins": [{ "name": "css-modules-lint" }]
  }
}

// 2. Vite plugin (optional)
// vite.config.ts
import cssModulesDts from 'css-modules-lint/vite';
export default defineConfig({
  plugins: [cssModulesDts()],
});

// 3. ESLint plugin (optional)
// eslint.config.js
import cssModulesLint from 'css-modules-lint/eslint';
export default [cssModulesLint.configs.recommended];

// 4. .gitignore
*.module.scss.d.ts
*.module.css.d.ts
*.module.less.d.ts

// 5. CI script
"scripts": {
  "lint:css": "css-modules-lint check"
}

// Run
npx css-modules-lint check
npx css-modules-lint generate