🎨 Transform to TailwindCSS

🚀 Effortlessly migrate legacy CSS to TailwindCSS

Automatically transform existing CSS styles into utility-first TailwindCSS classes

English | 简体中文

✨ 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

Global Installation

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

🎯 CSS Preprocessor Dependencies

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

# 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.

CLI Usage

# Transform a directory
totailwindcss playground

# Revert changes
totailwindcss playground --revert

🆕 Quick Example: Auto Safelist Generation

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.

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

// 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
}

<!-- 3. Write your components normally -->
<template>
  <div class="card">
    <h1 class="title">
      Hello World
    </h1>
  </div>
</template>

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

<!-- ✨ Auto-generated: ["p-5", "bg-gray-100", "text-2xl", "text-gray-800"] -->

🌈 Usage

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

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

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

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

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

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

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

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

🔧 Configuration Options

| Option | Type | Default | Description | | -------------------- | --------------- | ------------------------- | ----------------------------------------- | | 🐛 debug | boolean | false | Enable detailed transformation logs | | 📐 isRem | boolean | false | Convert px units to rem | | 🎯 include | FilterPattern | - | Files to process | | 🚫 exclude | FilterPattern | - | Files to ignore | | 📝 collectClasses | boolean | false | New Auto-collect generated classes | | 📂 outputPath | string | './safelist-classes.js' | New Output path for collected classes | | ⚡ skipIfNoChanges | boolean | true | New Skip generation if no changes |

⚠️ 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

🆕 Class Collection Feature

🎯 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.

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

// 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):

/**
 * 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

Other Configuration Options

debug

• 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.

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

isRem

• Type: boolean
• Default: false

Convert px units to rem units during the transformation process.

include/exclude

• 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

Before 😤

After 🎉

💖 Support the Project

If this project helps you, please consider giving it a ⭐!

📄 License

MIT © 2024-PRESENT Simon He