---

✨ Why Choose Transform to TailwindCSS?

🎯 Performance First - Reduce bundle size with TailwindCSS utility classes
🔄 Legacy Migration - Seamlessly upgrade old projects to modern TailwindCSS
⚡ Developer Experience - Maintain design system consistency
🛠️ Framework Agnostic - Support for Vue, React, Svelte, Astro and vanilla HTML
📝 Auto Safelist - 🆕 Automatically collect generated class names, never lose any
🔐 Circular Protection - 🆕 Smart protection to prevent infinite build loops
🚀 Build Optimized - 🆕 Smart skip, only regenerate when changes occur

> Want to use UnoCSS? Try transformToUnocss!

🚀 Quick Start

$3

``bash
npm install -g transform-to-tailwindcss


or

yarn global add transform-to-tailwindcss

or

pnpm add -g transform-to-tailwindcss
`

$3

From v0.0.49+, install CSS preprocessors you use in your project:

`bash


For Sass/SCSS support

npm install sass

For Less support

npm install less less-plugin-module-resolver

For Stylus support

npm install stylus
`

> Why? Using peerDependencies ensures compatibility with your project's preprocessor versions and avoids conflicts.

$3

`bash


Transform a directory

totailwindcss playground

Revert changes

totailwindcss playground --revert
`

$3

Transform your CSS and automatically generate a safelist for TailwindCSS in just 3 steps:

> ⚠️ For Tailwind CSS v3.x and below users: Run npm run build once before starting development to generate the initial safelist file.

`ts
// 1. Configure your build tool
// vite.config.ts
export default defineConfig({
plugins: [
viteTransformToTailwindcss({
collectClasses: true, // 🆕 Enable auto-collection
outputPath: './safelist-classes.js',
}),
],
})
`

`ts
// 2. Use in your TailwindCSS config
// tailwind.config.js
const { safelistClasses } = require('./safelist-classes.js')

module.exports = {
safelist: [...safelistClasses], // 🎯 Never lose classes again!
// ... rest of your config
}
`

`vue




`

🌈 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 /)],
})
`

🔧 Configuration Options

> ⚠️ Important Notes for Different Tailwind CSS Versions:
>
> - Tailwind CSS v4.x+: Works out of the box with dynamic class generation
> - Tailwind CSS v3.x and below: Requires initial build step
> 1. Configure plugin: collectClasses: true
> 2. Run build: npm run build (generates safelist file)
> 3. Start dev: npm run dev (uses generated safelist)
> 4. Repeat step 2 when adding new CSS transformations

$3

> 🎯 New Feature: Automatically collect all generated TailwindCSS class names for safelist configuration!

When using dynamic CSS transformations, TailwindCSS might not detect the generated classes during purging. The class collection feature solves this by automatically generating a safelist file containing all transformed classes.

> ⚠️ Important for Tailwind CSS v3.x and below users: You need to run a build once first to generate the safelist file, then start your dev server for normal behavior. This is because Tailwind CSS v3.x and below require the safelist to be available during the initial compilation process.

📝 Auto-Generate Safelist - Never Lose Classes Again

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

export default defineConfig({
plugins: [
viteTransformToTailwindcss({
collectClasses: true, // ✅ Enable class collection
outputPath: './config/safelist-classes.js', // 📂 Custom output path
skipIfNoChanges: true, // ⚡ Performance optimization
exclude: [
'config/*/', // 🚫 Exclude config directory
'safelist-classes.js', // 🚫 Exclude generated file
'tailwind.config.js', // 🚫 Exclude Tailwind config
],
}),
],
})
`

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

module.exports = {
content: ['./src/*/.{html,js,vue,ts,tsx}'],
safelist: [
...safelistClasses, // 🎯 Auto-generated classes
// Your other safelist items...
],
}
`

Generated file (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',
// ... more classes
]

module.exports = { safelistClasses }
export { safelistClasses }
`

Key Benefits:

- 🔄 Circular Dependency Protection: Smart detection prevents infinite build loops
- ⚡ Performance Optimized: Only regenerates when classes actually change
- 🛡️ Build-Safe: Multiple safeguards prevent duplicate generations
- 📊 Comprehensive: Collects classes from all transformation processes

> ⚠️ Workflow for Tailwind CSS v3.x and below:
>
> 1. Configure the plugin with collectClasses: true
> 2. Run npm run build (or your build command) once to generate safelist
> 3. Start your dev server with npm run dev
> 4. The generated classes will now be available during development

$3

$3

- Type: boolean
- Default: false

Enable debug mode to output detailed debugging logs during the transformation process. This is useful for troubleshooting and understanding the style transformation process.

`ts
// Example usage with debug mode enabled
viteTransformToTailwindcss({
debug: true,
isRem: false,
})
`

$3

- Type: boolean
- Default: false

Convert px units to rem units during the transformation process.

$3

- Type: FilterPattern

Filter patterns for including or excluding files during the transformation process.

🎯 Supported Features

✅ File Formats - .html | .tsx | .vue | .astro | .svelte`
✅ CSS Preprocessors - Sass, Less, Stylus
✅ Build Tools - Vite, Rollup, Webpack, Vue CLI, ESBuild
✅ IDE Support - VS Code Extension

🔗 Related Projects

- transform-to-tailwindcss-core - Browser-side CSS transformation engine

📈 Before & After Comparison

💖 Support the Project

📄 License

MIT © 2024-PRESENT Simon He