vite-plugin-jsx-css-modules

🚀 Vite 插件，自动将 JSX 中的 className 转换为 CSS Modules 引用。

特性

• ✅ 自动转换 - 无需手动导入和引用 CSS Modules
• ✅ 多文件支持 - 自动合并多个 CSS Module 文件
• ✅ 全局类名 - 兼容 UnoCSS/Tailwind 等工具类 CSS
• ✅ :global() 和 :local() 语法 - 明确标记全局/局部类名
• ✅ 动态类名 - 支持模板字符串和条件表达式
• ✅ 可定制 - 可配置文件匹配规则和导入方式
• ✅ 零配置 - 开箱即用

安装

npm install vite-plugin-jsx-css-modules -D
# 或
pnpm add vite-plugin-jsx-css-modules -D

快速开始

1. 配置 Vite

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import vitePluginJsxCssModules from 'vite-plugin-jsx-css-modules'

export default defineConfig({
  plugins: [
    vitePluginJsxCssModules(),
    react(),
  ],
})

2. 在组件中使用

// 之前：手动导入和引用
import styles from './App.module.css'
<div className={styles.container}>Hello</div>

// 之后：简洁优雅
import './App.module.css'
<div className="container">Hello</div>

就这么简单！插件会自动处理转换。

工作原理

插件在构建时自动转换你的 JSX：

// 输入
import './styles.module.css'

function App() {
  return <div className="container">Hello</div>
}

// 输出（自动转换）
import style_0 from './styles.module.css'
import { getMatcher as _getMatcher } from 'vite-plugin-jsx-css-modules/helpers'
const _styles = Object.assign({}, style_0)
const _matcher = _getMatcher(_styles, 'local')

function App() {
  return <div className={_matcher("container")}>Hello</div>
}

配置选项

选项说明

interface VitePluginJsxCssModulesOptions {
  // 匹配 CSS 模块文件的正则表达式
  styleFileReg?: Array<string | RegExp>
  
  // 默认类名处理方式
  prefer?: 'local' | 'global'
  
  // Helper 函数导入方式
  helperImportType?: 'esm' | 'cjs'
}

styleFileReg

• 类型: Array<string | RegExp>
• 默认值: [/\.(css|scss|sass|less)$/]

自定义需要处理的文件类型：

vitePluginJsxCssModules({
  // 支持 Stylus
  styleFileReg: [/\.module\.(css|scss|sass|less|styl)$/]
})

prefer

• 类型: 'local' | 'global'
• 默认值: 'local'

控制默认类名处理方式：

prefer: 'local' (默认)

<div className="container p-4">
  {/* container: 在 CSS Module 中查找 */}
  {/* p-4: 也在 CSS Module 中查找，找不到则保持原样 */}
</div>

推荐用于以 CSS Modules 为主要样式方案的项目。

prefer: 'global'

<div className="container p-4">
  {/* 所有类名都视为全局类名 */}
  {/* 要使用 CSS Module，必须明确标记 :local(container) */}
</div>

推荐用于以工具类 CSS（Tailwind/UnoCSS）为主要样式方案的项目。

helperImportType

• 类型: 'esm' | 'cjs'
• 默认值: 'esm'

控制 helper 函数导入方式：

// ESM (默认)
vitePluginJsxCssModules({ helperImportType: 'esm' })
// 生成：import { getMatcher } from '...'

// CJS
vitePluginJsxCssModules({ helperImportType: 'cjs' })
// 生成：const { getMatcher } = require('...')

使用示例

多个 CSS Module 文件

import './layout.module.css'   // 定义了 .container, .sidebar
import './theme.module.css'    // 定义了 .dark, .light

function App() {
  return (
    <div className="container dark">
      <aside className="sidebar">侧边栏</aside>
    </div>
  )
}
// ✅ 所有类名都能正确解析

混用工具类 CSS

import './styles.module.css'

function Hero() {
  return (
    <div className="hero p-4 mx-auto bg-blue-50">
      {/* hero: 来自 CSS Module */}
      {/* p-4, mx-auto, bg-blue-50: 工具类（保持原样） */}
    </div>
  )
}

:global() 和 :local() 语法

import './styles.module.css'

function Component() {
  return (
    <div className=":local(container) :global(p-4 mx-auto)">
      {/* 明确标记 container 为局部，p-4 mx-auto 为全局 */}
      内容
    </div>
  )
}

动态类名

import './styles.module.css'

function Button({ variant, disabled }) {
  return (
    <button 
      className={`btn btn-${variant} ${disabled && 'btn-disabled'}`}
    >
      {/* 模板字符串和动态表达式无缝支持 */}
      点击我
    </button>
  )
}

性能

• Helper 函数大小：~0.5KB gzipped
• 运行时开销：< 1ms（1000 次调用）
• 对开发/构建速度无影响

环境要求

• Node.js >= 16.0.0
• Vite ^4.0.0 || ^5.0.0

开发

# 安装依赖
pnpm install

# 构建
pnpm build

# 测试
pnpm test

# 本地开发
pnpm dev

许可证

MIT