Tailwind CSS Academy · Lesson

Content Paths and Purging

Configure the content array correctly to ensure Tailwind scans all files and removes unused classes in production builds.

Content Paths and Purging is a free Tailwind CSS Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Tailwind CSS Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Purging Matters

Tailwind CSS generates utility classes for every combination of your theme values — potentially hundreds of thousands of classes. Without pruning, the raw CSS output would be several megabytes. The purging process (officially called content scanning or tree-shaking) removes every class that does not appear in your source files, shrinking the production CSS to typically just 5–50 KB. Getting your content configuration right is essential for a lean build.

How Content Scanning Works

Tailwind scans the files you list in the content array and searches for string patterns that look like Tailwind class names. It does not execute your code — it does a simple text search. Any string that matches a known utility class is included in the output. This is why you must never construct class names dynamically by concatenating strings; the scanner won't find the full class name.

// BAD: Tailwind cannot detect 'text-red-500'
const color = 'red';
const cls = 'text-' + color + '-500';  // scanner sees 'text-' + 'red' + '-500'

// GOOD: Full class names are always present in source
const cls = isError ? 'text-red-500' : 'text-green-500';  // scanner sees both

Writing Content Glob Patterns

Glob patterns in the content array use standard glob syntax. The double-star ** matches any number of directory levels. Curly braces {} match multiple extensions. Be as specific as possible — avoid patterns that are too broad (like ./**/*) as they will slow down scanning by including files like images and JSON that cannot contain class names.

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{html,js,jsx,ts,tsx,vue}',
    './components/**/*.{js,jsx,ts,tsx}',
    './pages/**/*.{js,jsx,ts,tsx}',
    './layouts/**/*.html',
    // Include a specific file
    './public/index.html',
    // Include node_modules (for UI library components)
    './node_modules/@my-ui/components/dist/**/*.js',
  ],
};

Content for Popular Frameworks

Different frameworks organize their files differently. Here are the correct content patterns for the most popular setups. Next.js needs app/ and pages/ directories. Vue projects typically use .vue files. Laravel's Blade templates live in resources/views/. Always check that your entry files (like index.html or layout files) are included explicitly if they sit outside your glob patterns.

// Next.js App Router
content: ['./app/**/*.{js,jsx,ts,tsx}', './components/**/*.{js,jsx,ts,tsx}']

// Vue + Vite
content: ['./index.html', './src/**/*.{vue,js,ts}']

// Laravel Blade
content: ['./resources/**/*.blade.php', './resources/**/*.js']

// Nuxt 3 (usually auto-detected, but explicit)
content: ['./components/**/*.vue', './pages/**/*.vue', './layouts/**/*.vue']

The safelist Option

Sometimes classes are constructed at runtime and cannot be detected by static scanning — for example, class names built from CMS content, user input, or API responses. Use the safelist option to force-include specific classes or patterns, ensuring they are always in the output regardless of whether the scanner finds them. You can safelist individual strings or regex patterns.

// tailwind.config.js
module.exports = {
  safelist: [
    // Individual classes
    'text-red-500',
    'bg-blue-100',
    // Pattern: all bg-{color}-{shade} for red and green
    {
      pattern: /bg-(red|green)-(100|200|300|400|500)/,
    },
    // Include hover variants too
    {
      pattern: /bg-red-(400|500)/,
      variants: ['hover', 'focus'],
    },
  ],
};

The blocklist Option

The blocklist option is the opposite of safelist — it prevents specific classes from being included in the output even if the scanner finds them in your source. This is useful for enforcing team conventions (preventing use of deprecated utility names) or reducing output size by explicitly excluding utilities you know you will never use, like certain font size or animation classes.

// tailwind.config.js
module.exports = {
  blocklist: [
    // Prevent these classes from being generated
    'container',
    'prose',
    'animate-bounce',
  ],
};

Content Transformers

For files that need preprocessing before scanning — like .pug templates, .md files, or custom template engines — Tailwind's content.transform option lets you provide a function that transforms the raw file content into a string of class names. This is rarely needed but powerful for edge cases where the file format hides class names in a non-obvious way.

// tailwind.config.js
module.exports = {
  content: {
    files: ['./src/**/*.{html,js}'],
    transform: {
      // Transform markdown files before scanning
      md: (content) => {
        // Render to HTML first so class names are visible
        return renderMarkdownToHtml(content);
      },
    },
  },
};

Content Extraction for Component Libraries

If your project uses a third-party component library that ships pre-built JavaScript with embedded Tailwind classes, you need to include the library's dist files in your content array. Many popular Tailwind component libraries (like Flowbite, daisyUI, or custom internal libraries) work this way. Add the path to their built JavaScript output so the scanner can detect which classes they use.

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{html,js,jsx,ts,tsx}',
    // Include prebuilt components from a library
    './node_modules/flowbite/**/*.js',
    // Or a local package in a monorepo
    '../../packages/ui/src/**/*.{js,jsx,ts,tsx}',
  ],
};

Verifying Your Content Config

To confirm that your content configuration is working correctly, run npx tailwindcss build and check the output file size. A well-configured production build should be under 50 KB (often much less). You can also run the Tailwind CLI with the --watch flag during development to see real-time compilation and verify that adding a new class immediately appears in the output.

# Build and check output size
npx tailwindcss -i ./src/input.css -o ./dist/output.css --minify

# Check the size
wc -c < ./dist/output.css  # bytes
ls -lh ./dist/output.css   # human-readable

# Watch mode for development
npx tailwindcss -i ./src/input.css -o ./dist/output.css --watch

JIT and On-Demand Class Generation

Tailwind v3 uses a Just-In-Time (JIT) engine by default. Unlike the old PurgeCSS approach, JIT generates classes on demand as you write them, scanning your content files in real time during development. This means your development CSS is already small and matches production exactly — there is no separate purging step in v3. The content array serves both development scanning and production optimization.

Common Content Configuration Mistakes

The most common mistake is missing files from the content array — classes from those files get purged in production. Another mistake is dynamic class construction where the full class name never appears as a string. A third issue is forgetting template files in non-JS frameworks. Always test your production build locally with NODE_ENV=production to catch purging issues before deploying.

// Common mistake: incomplete pattern
content: ['./src/**/*.js']  // MISSES .jsx, .tsx, .html files!

// Better: cover all template types
content: ['./src/**/*.{html,js,jsx,ts,tsx}']

// Also common: missing the root HTML file
content: [
  './index.html',              // don't forget this!
  './src/**/*.{js,jsx,ts,tsx}'
]

Quick Check

Test your understanding of Tailwind's content paths and class purging.

Lesson Recap

In this lesson you learned: the content array tells Tailwind which files to scan for class names, full class names must always appear as literal strings for the scanner to detect them, and the safelist option force-includes classes that cannot be statically detected. Next up we explore the difference between extending and overriding the Tailwind theme.

Frequently asked questions

Is the “Content Paths and Purging” lesson free?

Yes — the full text of “Content Paths and Purging” is free to read here on the web, and the Tailwind CSS Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Tailwind CSS Academy course, upgrade to CoddyKit PRO.

What will I learn in “Content Paths and Purging”?

Configure the content array correctly to ensure Tailwind scans all files and removes unused classes in production builds. You practise Tailwind CSS Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Tailwind CSS Academy?

No prior experience is required. Tailwind CSS Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Content Paths and Purging” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Tailwind CSS Academy lesson?

Yes. Every Tailwind CSS Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Tailwind CSS Academy