Next.js（TypeScript + CSSModules）+ happy-css-modulesで存在しないクラス名へのアクセスを防ぐ 💻

前回は、Next.js（TypeScript + CSSModules）+ biomeの環境を構築しました。

blog.kimizuka.org

今回は、それに加えて、happy-css-modules を導入します。

github.com

happy-css-modules とは

importしているCSSModulesのクラス名をサジェストしたり、

存在しないクラス名にエラーを出したり、

CSSModulesのファイルにジャンプできるようになったりする、

便利なツールです。

歴史のある typed-css-modules や、happy-css-modulesの作者の最新作である css-modules-kit と迷ったのですが、色々試した結果、しばらくは、happy-css-modules を使っていこうと思いました。

github.com
github.com

設定方法

❶ happy-css-modulesとnpm-run-allの導入

yarn add -D happy-css-modules npm-run-all

❷ package.jsonの編集

{
  "name": "nextjs",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "run-p dev:next dev:css",
    "dev:next": "next dev --turbopack",
    "dev:css": "hcm 'src/**/*.module.css' --watch",
    "build": "next build --turbopack",
    "start": "next start",
    "lint": "biome check --write ./src",
    "update": "ncu -u"
  },
  "dependencies": {
    "next": "15.3.3",
    "react": "^19.1.0",
    "react-dom": "^19.1.0"
  },
  "devDependencies": {
    "@biomejs/biome": "1.9.4",
    "@types/node": "^22",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "happy-css-modules": "^4.0.0",
    "npm-check-updates": "^18.0.1",
    "npm-run-all": "^4.1.5",
    "typescript": "^5"
  }
}

基本的にはこれだけです。

yarn dev

を実行すると、next dev と hcm 'src/**/*.module.css' --watch が走ります。
なので、CSSModulesのファイルを編集し保存すると、

.module.css.d.ts
.module.css.d.ts.map

が、自動で生成され、前述の挙動が実現できます。

僕は、VSCodeを使っているので、setting.jsonに、

"explorer.fileNesting.patterns": {
  "*.module.css": "*.module.css.d.ts, *.module.css.d.ts.map"
}

を追記して、自動で生成されるファイルを隠しています。
前回のbiomeの設定と併せると、

{
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit"
  },
  "editor.formatOnSave": true,
  "explorer.fileNesting.enabled": true,
  "explorer.fileNesting.patterns": {
    "*.module.css": "*.module.css.d.ts, *.module.css.d.ts.map"
  },
  "files.associations": {
    "*.css": "css"
  },
  "[javascript][typescript][javascriptreact][typescriptreact][json][jsonc]": {
    "editor.tabSize": 2,
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[css]": {
    "editor.tabSize": 2,
    "editor.defaultFormatter": "biomejs.biome"
  }
}