ViteTailwind CSSError Fix2026 Updated

Vite Tailwind CSS Not Purging— Unused Styles Fixed [2026]

Also covers: content paths · dynamic class names · safelist · JIT mode · bundle size audit

January 20265 min readTailwind CSS v3/v4 · Vite 5/6 · TypeScript

⚡ Symptoms

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

tailwind.config.ts — content paths must match your source files
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.

1

Set Correct Content Paths in tailwind.config

Root cause — wrong or missing content array
2 min
tailwind.config.ts — correct content paths
import 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 Config

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

2

Never Build Class Names Dynamically

Dynamic classes purged in production — class missing
2 min
Static vs dynamic class names
// ❌ 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
)
3

Use safelist for Dynamic or Runtime Classes

CMS content or API-driven class names that can't be static
3 min
tailwind.config.ts — safelist patterns
export 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.

4

Verify Tailwind Is Running in JIT Mode

Tailwind v2 — JIT not enabled, large dev CSS bundle
2 min
Tailwind v3+ — JIT is always on; v2 requires opt-in
// 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 autoprefixer
5

Measure and Audit Bundle Size

Confirm purging is working after fixes
2 min
Measure CSS bundle size after build
# 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 count

Prevention

Frequently Asked Questions

Why are some Tailwind classes missing in production?+
Tailwind scans your source files to find every class name used, then generates only those classes. If a class is built dynamically (e.g. 'text-' + color) or the file containing it is not in the content paths, Tailwind won't see it and won't generate it. The fix is to use complete class names as static strings.
Why is my Tailwind production bundle still very large?+
If content paths are not set correctly, Tailwind falls back to generating all utility classes — which is 3–4MB of CSS. Check that tailwind.config.ts content array matches your actual source file locations. A properly purged Tailwind bundle is typically 5–15KB.
What is Tailwind JIT mode and is it always on?+
JIT (Just-in-Time) mode generates classes on demand as Vite encounters them during development, instead of pre-generating all classes. Since Tailwind v3, JIT is always on by default — there is no need to enable it. If you are on Tailwind v2, you need to set mode: 'jit' in tailwind.config.js.
How do I use Tailwind with dynamic class names?+
Never build partial class names at runtime. Instead, use a mapping object that contains complete class strings: const colors = { red: 'text-red-500', blue: 'text-blue-500' }. This way the complete class names appear as static strings in your source and Tailwind's scanner includes them.
What is the Tailwind safelist and when should I use it?+
The safelist tells Tailwind to always generate specific classes regardless of whether they appear in your source files. Use it for classes generated by a CMS, fetched from an API, or built at runtime. You can also use regex patterns to safelist a group: { pattern: /bg-(red|blue|green)-(100|500|900)/ }.
Does Tailwind purging work with CSS-in-JS or runtime styling?+
No. Tailwind's scanner reads static source files — it cannot scan runtime-generated class strings. If you generate Tailwind class names from API data or dynamic logic, use the safelist option in tailwind.config.ts to explicitly list or pattern-match those classes.

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