vite-plugin-scoped-tailwind

一款用于在 Vite 构建产物中为 CSS 选择器与 JS 中静态类字符串添加作用域前缀的插件。

目标场景

• 给组件本地定义的类名添加前缀，避免与全局样式或第三方库冲突。
• 在不影响 Tailwind 工具类和 CSS 变量声明值的情况下，自动在构建输出中同步更新模板与样式。

主要特性

• 使用 PostCSS 解析器只在选择器中修改类名，避免误改 CSS 值或变量。
• 在 JS chunk 中使用 Babel AST 定位静态 class / className 字面量与静态 template literal，并用 magic-string 做精确替换以保留 sourcemap。
• 支持 include / exclude / dryRun / mode（ast/regex）选项，且暴露 transformClass 回调以自定义替换逻辑。

安装

• npm

npm install --save-dev vite-plugin-scoped-tailwind

• pnpm

pnpm add -D vite-plugin-scoped-tailwind

• yarn

yarn add -D vite-plugin-scoped-tailwind

快速使用示例（Vite）

在 vite.config.ts 中：

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import vitePluginScopedTailwind from 'vite-plugin-scoped-tailwind';

export default defineConfig({
  plugins: [
    vue(),
    vitePluginScopedTailwind('scoped-', {
      include: /assets\/.*\.js$/,
      dryRun: false,
      mode: 'ast',
      transformClass: (cls, meta) => {
        // meta: { fileName, type }
        if (!cls) return cls;
        return `scoped-${cls}`;
      },
    }),
  ],
});

配置说明

• prefix（第一个参数）: 默认 'scoped-'，将作为前缀添加到类名上。
• include / exclude: 控制要处理的文件（字符串 / 正则 / 数组 / 函数）。默认只处理 assets 下的 .js 文件以减少开销。
• dryRun: true 时不写入修改，仅输出将会被修改的文件列表。
• mode: 'ast'（默认，稳健）或 'regex'（更快但风险更高）。
• transformClass: (cls, meta) => string，自定义单个 class token 的映射策略。

Tailwind 使用建议

• 如果项目使用 Tailwind，通常不要无差别地给所有类加前缀（会破坏 Tailwind 工具类）。推荐只前缀组件本地定义的类（插件支持通过扫描 CSS 选择器白名单来实现）。

使用场景示例

• 仅前缀组件选择器并在 JS 中同步替换：

vitePluginScopedTailwind('scoped-', { include: /assets\/.*\.js$/ });

调试与 dryRun

• 使用 dryRun: true 可以在构建时仅输出将被修改的文件，便于确认影响范围。

测试与构建

• 在开发中可用 pnpm run build 构建插件并在 examples 中验证。
• 项目包含 Vitest 单元测试：pnpm run test:unit。

联系与贡献

• 欢迎反馈 issue 或提交 PR。README 中有示例和测试用例，便于复现问题。

许可证

• MIT