Vite Tailwind CSS Not Purging— Unused Styles Fixed [2026]
Also covers: content paths · dynamic class names · safelist · JIT mode · bundle size audit
⚡ Symptoms
# Production CSS is 3-4MB — Tailwind not purging (should be ~10KB)
# OR: class works in dev but disappears in production build
# Dynamic class like "text-" + color → purged → missing in prod✅ Fix — check content paths first
export default {
content: [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}", // ← must cover all files using Tailwind classes
],
// ...
}Why Tailwind Styles Are Missing or Bundle Is Too Large
Tailwind CSS scans your source files as plain text to find class names, then generates only the CSS for those classes. If content paths miss some files, those files' classes are not generated. If content paths are too broad or missing entirely, Tailwind generates everything — a 3–4MB CSS file.
Set Correct Content Paths in tailwind.config
Root cause — wrong or missing content arrayimport type { Config } from "tailwindcss"
export default {
content: [
// ✅ Standard React + Vite project:
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
// ✅ If using shadcn/ui components:
"./components/**/*.{js,ts,jsx,tsx}",
// ✅ If using a UI library with Tailwind classes:
"./node_modules/@your-ui-lib/components/**/*.{js,ts,jsx,tsx}",
// ✅ Monorepo — include packages that use Tailwind:
"../../packages/ui/src/**/*.{js,ts,jsx,tsx}",
],
theme: { extend: {} },
plugins: [],
} satisfies ConfigAfter changing content paths, run npm run build and check the dist/assets/*.css file size. A correctly purged Tailwind bundle for a typical app is 8–20KB. If it's still 3MB+, the content paths aren't matching your files.
Never Build Class Names Dynamically
Dynamic classes purged in production — class missing// ❌ Dynamic — Tailwind scanner can't see 'text-red-500' as a string
const color = "red"
const size = "500"
const className = `text-${color}-${size}` // purged — class never appears as literal
// ❌ Also wrong — partial string concatenation
const btn = "bg-" + variant // "bg-" is not a complete class
// ✅ Complete class names as static strings — always visible to scanner
const colorMap = {
red: "text-red-500", // ← complete literal string
blue: "text-blue-500", // ← complete literal string
green: "text-green-500", // ← complete literal string
}
const className = colorMap[color] // scanner sees all three complete strings
// ✅ Conditional classes — always use complete strings
const buttonClass = variant === "primary"
? "bg-indigo-600 text-white hover:bg-indigo-700" // complete strings
: "bg-gray-100 text-gray-900 hover:bg-gray-200" // complete strings
// ✅ clsx/cn utility — complete class strings in all branches
import { cn } from "@/lib/utils"
const cls = cn(
"px-4 py-2 rounded font-medium",
isActive && "bg-indigo-600 text-white", // complete strings
!isActive && "bg-gray-100 text-gray-700" // complete strings
)Use safelist for Dynamic or Runtime Classes
CMS content or API-driven class names that can't be staticexport default {
content: ["./src/**/*.{js,ts,jsx,tsx}"],
safelist: [
// Exact class names — always generated
"text-red-500",
"bg-green-100",
"border-blue-300",
// Pattern — generate entire family
{
pattern: /bg-(red|blue|green|yellow|purple)-(100|500|900)/,
variants: ["hover", "focus"], // include hover:bg-red-500 etc.
},
// For status badges from API/CMS
{
pattern: /text-(red|green|yellow|gray)-d{3}/,
},
],
theme: { extend: {} },
plugins: [],
}Use safelist sparingly — each safelisted pattern adds CSS for every matching combination. Safelisting /bg-.*/ would include ALL background color utilities and defeat the purpose of purging.
Verify Tailwind Is Running in JIT Mode
Tailwind v2 — JIT not enabled, large dev CSS bundle// tailwind.config.js (v2 — requires explicit JIT mode)
module.exports = {
mode: "jit", // ← required in v2
purge: ["./src/**/*.{js,ts,jsx,tsx}"], // v2 uses 'purge', not 'content'
// ...
}
// tailwind.config.ts (v3/v4 — JIT always on, no mode needed)
export default {
content: ["./src/**/*.{js,ts,jsx,tsx}"], // v3 uses 'content'
// mode: "jit" is redundant and not needed in v3+
}
// Check your Tailwind version:
npx tailwindcss --version
// Upgrade to v3 if still on v2:
npm install -D tailwindcss@latest postcss autoprefixerMeasure and Audit Bundle Size
Confirm purging is working after fixes# Build and check CSS size
npm run build
ls -lh dist/assets/*.css
# Expected sizes:
# ✅ Properly purged Tailwind: 5–25KB (gzipped: 2–8KB)
# ❌ Not purged: 3–4MB (gzipped: 400–600KB)
# Using vite-bundle-visualizer to inspect output:
npm install -D rollup-plugin-visualizer
# vite.config.ts:
import { visualizer } from "rollup-plugin-visualizer"
export default defineConfig({
plugins: [
react(),
visualizer({ open: true, filename: "stats.html" }),
],
})
# Build → stats.html opens automatically showing bundle breakdown
# PurgeCSS manual audit — list all generated classes:
npx tailwindcss -i ./src/index.css -o /tmp/out.css --minify
wc -c /tmp/out.css # check byte countPrevention
- Set content paths to match all files that use Tailwind classes — check with a build and inspect CSS size
- Never build class names by concatenating strings at runtime — always use complete literal class names
- Use a colorMap / variantMap object with complete class strings instead of template literals
- Use safelist only for classes driven by external data (CMS, API) — with specific patterns, not wildcards
- After any tailwind.config.ts change, run npm run build and check the CSS file size in dist/assets/
- Upgrade to Tailwind v3 if on v2 — JIT is always on and content replaces purge
Frequently Asked Questions
Why are some Tailwind classes missing in production?+−
Why is my Tailwind production bundle still very large?+−
What is Tailwind JIT mode and is it always on?+−
How do I use Tailwind with dynamic class names?+−
What is the Tailwind safelist and when should I use it?+−
Does Tailwind purging work with CSS-in-JS or runtime styling?+−
Need Expert Help?
We Build Optimised Vite + Tailwind Applications
Softplix engineers configure Vite and Tailwind for minimal CSS bundles, fast HMR, and production-optimised builds. Let us help.
Talk to an Engineer