# 🎨 Transform to TailwindCSS
[](https://badge.fury.io/js/transform-to-tailwindcss)
[](https://www.npmjs.com/package/transform-to-tailwindcss)
[](https://opensource.org/licenses/MIT)
[](https://github.com/Simon-He95/transformToTailwindcss)
**🚀 轻松将传统 CSS 迁移到 TailwindCSS**
_自动将现有 CSS 样式转换为实用优先的 TailwindCSS 类_
[English](./README.md) | [简体中文](./README_zh.md)
你好世界
```
## 🌈 Usage
Vite
```ts
// vite.config.ts
import { vitePluginTransformTotailwindcss } from 'transform-to-tailwindcss'
export default defineConfig({
plugins: [vitePluginTransformTotailwindcss(/* options */)],
})
```
Rollup
```ts
// rollup.config.js
import { resolve } from 'node:path'
import { rollupTransformTotailwindcss } from 'transform-to-tailwindcss'
export default {
plugins: [rollupTransformTotailwindcss(/* options */)],
}
```
Webpack
```ts
// webpack.config.js
module.exports = {
/* ... */
plugins: [
require('transform-to-tailwindcss').webpackTransformTotailwindcss({
/* options */
}),
],
}
```
Vue CLI
```ts
// vue.config.js
module.exports = {
configureWebpack: {
plugins: [
require('transform-to-tailwindcss').webpackTransformTotailwindcss({
/* options */
}),
],
},
}
```
Esbuild
```ts
// 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 及以下版本**：需要初始构建步骤
> 1. 配置插件：`collectClasses: true`
> 2. 运行构建：`npm run build`（生成 safelist 文件）
> 3. 启动开发：`npm run dev`（使用生成的 safelist）
> 4. 添加新的 CSS 转换时重复步骤 2
### 🆕 类名收集功能
> 🎯 **新功能**：自动收集所有生成的 TailwindCSS 类名，用于 `safelist` 配置！
当使用动态 CSS 转换时，TailwindCSS 在清除阶段可能无法检测到生成的类名。类名收集功能通过自动生成包含所有转换类名的 safelist 文件来解决这个问题。
> ⚠️ **Tailwind CSS v3.x 及以下版本用户重要提示**：您需要**先运行一次构建**来生成 safelist 文件，然后再启动开发服务器才能正常工作。这是因为 Tailwind CSS v3.x 及以下版本在初始编译过程中需要 safelist 可用。
📝 自动生成 Safelist - 再也不丢失类名
```ts
// 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 配置
],
}),
],
})
```
```ts
// 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`)：**
```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 及以下版本工作流程**：
>
> 1. 配置插件启用 `collectClasses: true`
> 2. 运行 `npm run build`（**首次必须**）生成 safelist 文件
> 3. 启动开发服务器 `npm run dev`
> 4. 生成的类名现在可以在开发过程中正常使用
### 其他配置选项
### `debug`
- **类型:** `boolean`
- **默认值:** `false`
启用调试模式，在转换过程中输出详细的调试日志。这对于排查问题和理解样式转换过程非常有用。
```ts
// 启用调试模式的使用示例
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 扩展](https://github.com/Simon-He95/totailwindcss)
## 🔗 相关项目
- [transform-to-tailwindcss-core](https://github.com/Simon-He95/transform-to-tailwindcss-core) - 浏览器端 CSS 转换引擎
## 📈 转换前后对比
### 转换前 😤
### 转换后 🎉
## 💖 支持项目
**如果这个项目对你有帮助，请考虑给个 ⭐！**
[](https://github.com/Simon-He95/sponsor)
## 📄 开源协议
[MIT](./license) © 2024-PRESENT [Simon He](https://github.com/Simon-He95)