使用honey-css-modules快速上手指南

什么是honey-css-modules

honey-css-modules是一个为TypeScript项目提供完整CSS Modules支持的解决方案。它通过一系列工具链的配合，为开发者提供类型安全的CSS Modules开发体验，包括：

1. 编辑器智能提示支持
2. 类型定义生成
3. 静态类型检查
4. 代码质量检查

环境准备

编辑器插件安装

首先需要为你的代码编辑器安装CSS Modules语言支持插件。不同编辑器的安装方式如下：

• VS Code用户：安装CSS Modules Kit扩展
• Neovim用户：需要安装ts-plugin并进行相应配置
• Zed编辑器：参考相关文档进行配置
• 其他编辑器：目前Emacs和WebStorm暂不支持

编辑器插件会为CSS Modules文件提供语法高亮、自动补全等语言特性支持。

核心工具链配置

代码生成器安装

虽然编辑器插件能提供类型提示，但在命令行执行类型检查时(tsc)这些类型不会生效。为此需要安装代码生成器：

npm install --save-dev @css-modules-kit/codegen

然后在package.json中配置构建脚本：

{
  "scripts": {
    "gen": "cmk",
    "build": "run-s -c gen build:*",
    "build:vite": "vite build",
    "lint": "run-s -c gen lint:*"
  }
}

这样在执行构建或lint前，会先运行cmk命令生成*.module.css.d.ts类型定义文件。

TypeScript配置

需要调整tsconfig.json以确保类型系统正常工作：

1. include配置：确保包含CSS Modules文件

   • 推荐：["src"]或["src/**/*"]
   • 不推荐：仅包含TypeScript文件如["src/**/*.ts"]

2. rootDirs配置：需要包含生成目录

   {
     "compilerOptions": {
       "rootDirs": [".", "generated"]
     }
   }
   

完整配置示例：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "NodeNext",
    "strict": true,
    "rootDirs": [".", "generated"]
  }
}

可选增强功能

代码质量检查

项目提供了两种风格的lint插件，功能相同但适用于不同工具链：

1. stylelint插件：适合已使用stylelint的项目
2. eslint插件：适合已使用eslint的项目

选择其中一种安装即可为CSS Modules添加静态检查能力。

自定义配置

可以通过tsconfig.json中的cmkOptions字段自定义代码生成行为，例如：

• 生成目录位置
• 文件匹配模式
• 类型定义格式等

最佳实践建议

1. 项目结构：建议将CSS Modules文件与组件文件放在同一目录
2. 命名规范：使用.module.css后缀明确标识CSS Modules文件
3. 构建流程：确保在类型检查和构建前执行代码生成
4. 版本控制：建议将生成的类型定义文件加入.gitignore

通过以上配置，你的TypeScript项目将获得完整的CSS Modules支持，包括开发时的智能提示和构建时的类型安全保证。