🎨 Transform to TailwindCSS

June 25, 2025 · View on GitHub

🎨 Transform to TailwindCSS

🚀 轻松将传统 CSS 迁移到 TailwindCSS

自动将现有 CSS 样式转换为实用优先的 TailwindCSS 类

✨ 为什么选择 Transform to TailwindCSS？

🎯 性能优先 - 通过利用 TailwindCSS 的实用类减少打包体积 🔄 遗留迁移 - 无缝将老项目升级到现代化的 TailwindCSS ⚡ 开发体验 - 保持设计系统的一致性 🛠️ 框架无关 - 支持 Vue、React、Svelte、Astro 和原生 HTML 📝 自动 Safelist - 🆕 自动收集生成的类名，永不丢失 🔐 循环保护 - 🆕 智能防护，避免无限构建循环 🚀 构建优化 - 🆕 智能跳过，仅在变化时重新生成

想要使用 UnoCSS？试试 transformToUnocss！

� 快速开始

全局安装

npm install -g transform-to-tailwindcss
# 或
yarn global add transform-to-tailwindcss
# 或
pnpm add -g transform-to-tailwindcss

CLI 使用

# 转换目录
totailwindcss playground

# 撤销更改
totailwindcss playground --revert

🆕 快速示例：自动 Safelist 生成

仅需 3 步即可转换 CSS 并自动为 TailwindCSS 生成 safelist：

⚠️ Tailwind CSS v3.x 及以下版本用户注意：首次启动开发前需要运行一次 npm run build 来生成初始 safelist 文件。

// 1. 配置构建工具
// vite.config.ts
export default defineConfig({
  plugins: [
    viteTransformToTailwindcss({
      collectClasses: true, // 🆕 启用自动收集
      outputPath: './safelist-classes.js',
    }),
  ],
})

// 2. 在 TailwindCSS 配置中使用
// tailwind.config.js
const { safelistClasses } = require('./safelist-classes.js')

module.exports = {
  safelist: [...safelistClasses], // 🎯 再也不丢失类名！
  // ... 其他配置
}

<!-- 3. 正常编写组件 -->
<template>
  <div class="card">
    <h1 class="title">
      你好世界
    </h1>
  </div>
</template>

<style scoped>
.card {
  padding: 20px;
  background: #f3f4f6;
}
.title {
  font-size: 24px;
  color: #1f2937;
}
</style>

<!-- ✨ 自动生成: ["p-5", "bg-gray-100", "text-2xl", "text-gray-800"] -->

🌈 Usage

Vite

// vite.config.ts
import { vitePluginTransformTotailwindcss } from 'transform-to-tailwindcss'

export default defineConfig({
  plugins: [vitePluginTransformTotailwindcss(/* options */)],
})

Rollup

// rollup.config.js
import { resolve } from 'node:path'
import { rollupTransformTotailwindcss } from 'transform-to-tailwindcss'

export default {
  plugins: [rollupTransformTotailwindcss(/* options */)],
}

Webpack

// webpack.config.js
module.exports = {
  /* ... */
  plugins: [
    require('transform-to-tailwindcss').webpackTransformTotailwindcss({
      /* options */
    }),
  ],
}

Vue CLI

// vue.config.js
module.exports = {
  configureWebpack: {
    plugins: [
      require('transform-to-tailwindcss').webpackTransformTotailwindcss({
        /* options */
      }),
    ],
  },
}

Esbuild

// esbuild.config.js
import { build } from 'esbuild'
import { esbuildTransformTotailwindcss } from 'transform-to-tailwindcss'

build({
  plugins: [esbuildTransformTotailwindcss(/* options */)],
})

🔧 选项配置

选项	类型	默认值	描述
🐛 `debug`	`boolean`	`false`	启用详细的转换日志
📐 `isRem`	`boolean`	`false`	将 px 单位转换为 rem
🎯 `include`	`FilterPattern`	-	要处理的文件
🚫 `exclude`	`FilterPattern`	-	要忽略的文件
📝 `collectClasses`	`boolean`	`false`	新功能自动收集生成的类名
📂 `outputPath`	`string`	`'./safelist-classes.js'`	新功能收集类名的输出路径
⚡ `skipIfNoChanges`	`boolean`	`true`	新功能无变化时跳过生成

⚠️ 不同 Tailwind CSS 版本的重要说明：

Tailwind CSS v4.x+：开箱即用，支持动态类名生成

Tailwind CSS v3.x 及以下版本：需要初始构建步骤

配置插件：collectClasses: true

运行构建：npm run build（生成 safelist 文件）

启动开发：npm run dev（使用生成的 safelist）

添加新的 CSS 转换时重复步骤 2

🆕 类名收集功能

🎯 新功能：自动收集所有生成的 TailwindCSS 类名，用于 safelist 配置！

当使用动态 CSS 转换时，TailwindCSS 在清除阶段可能无法检测到生成的类名。类名收集功能通过自动生成包含所有转换类名的 safelist 文件来解决这个问题。

⚠️ Tailwind CSS v3.x 及以下版本用户重要提示：您需要先运行一次构建来生成 safelist 文件，然后再启动开发服务器才能正常工作。这是因为 Tailwind CSS v3.x 及以下版本在初始编译过程中需要 safelist 可用。

📝 自动生成 Safelist - 再也不丢失类名

// vite.config.js
import { viteTransformToTailwindcss } from 'transform-to-tailwindcss'

export default defineConfig({
  plugins: [
    viteTransformToTailwindcss({
      collectClasses: true, // ✅ 启用类名收集
      outputPath: './config/safelist-classes.js', // 📂 自定义输出路径
      skipIfNoChanges: true, // ⚡ 性能优化
      exclude: [
        'config/**/*', // 🚫 排除配置目录
        'safelist-classes.js', // 🚫 排除生成的文件
        'tailwind.config.js', // 🚫 排除 Tailwind 配置
      ],
    }),
  ],
})

// tailwind.config.js
const { safelistClasses } = require('./config/safelist-classes.js')

module.exports = {
  content: ['./src/**/*.{html,js,vue,ts,tsx}'],
  safelist: [
    ...safelistClasses, // 🎯 自动生成的类名
    // 您的其他 safelist 项目...
  ],
}

生成的文件 (safelist-classes.js)：

/**
 * Auto-generated safelist classes for Tailwind CSS
 * Generated at: 2024-01-15T10:30:00.000Z
 * Total classes: 156
 * Skip if no changes: true
 */

const safelistClasses = [
  'bg-blue-500',
  'text-white',
  'hover:bg-blue-600',
  'md:p-6',
  // ... 更多类名
]

module.exports = { safelistClasses }
export { safelistClasses }

主要优势：

🔄 循环依赖保护：智能检测防止无限构建循环
⚡ 性能优化：只在类名实际变化时重新生成
🛡️ 构建安全：多重保护防止重复生成
📊 全面覆盖：收集所有转换过程中的类名

⚠️ Tailwind CSS v3.x 及以下版本工作流程：

配置插件启用 collectClasses: true

运行 npm run build（首次必须）生成 safelist 文件

启动开发服务器 npm run dev

生成的类名现在可以在开发过程中正常使用

其他配置选项

`debug`

类型: boolean
默认值: false

启用调试模式，在转换过程中输出详细的调试日志。这对于排查问题和理解样式转换过程非常有用。

// 启用调试模式的使用示例
viteTransformToTailwindcss({
  debug: true,
  isRem: false,
})

`isRem`

类型: boolean
默认值: false

在转换过程中将 px 单位转换为 rem 单位。

`include`/`exclude`

类型: FilterPattern

用于在转换过程中包含或排除文件的过滤模式。

🎯 支持特性

✅ 文件格式 - .html | .tsx | .vue | .astro | .svelte ✅ CSS 预处理器 - Sass、Less、Stylus ✅ 构建工具 - Vite、Rollup、Webpack、Vue CLI、ESBuild ✅ IDE 支持 - VS Code 扩展

🎨 Transform to TailwindCSS

🎨 Transform to TailwindCSS

✨ 为什么选择 Transform to TailwindCSS？

� 快速开始

全局安装

CLI 使用

🆕 快速示例：自动 Safelist 生成

🌈 Usage

🔧 选项配置

🆕 类名收集功能

其他配置选项

`debug`

`isRem`

`include`/`exclude`

🎯 支持特性

🔗 相关项目

📈 转换前后对比

转换前 😤

转换后 🎉

💖 支持项目

📄 开源协议