Tailwind CSS - Content Configuration

Tailwind CSS: Content Configuration

The content configuration in your tailwind.config.js file is the most critical setting for modern Tailwind CSS. It tells Tailwind’s Just-In-Time (JIT) engine which files to scan for class names. Tailwind then generates only the CSS that you are actually using in your project, resulting in a highly optimized, production-ready stylesheet.

Configuring Your Source Paths

The content key accepts an array of glob patterns to match your template files. It’s crucial to be comprehensive and include paths to all files that contain Tailwind class names, such as HTML files, JavaScript components (React, Vue, Svelte), and any other template sources.

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/pages/**/*.{js,ts,jsx,tsx}',
    './src/components/**/*.{js,ts,jsx,tsx}',
    './public/index.html' // If you have a root HTML file
  ],
  // ...
}

Pattern Configuration Best Practices

• Be Specific: Provide the most specific paths possible. Avoid overly broad patterns like './**/*.{js,html}' which might unnecessarily scan node_modules or build output directories, slowing down your build.
• Include All Extensions: Make sure to include all relevant file extensions. For a React/TypeScript project, you’ll need {js,ts,jsx,tsx}.
• Framework-Specific Paths: Different frameworks have different file structures. For example, a Next.js project might use './app/**/*.{js,ts,jsx,tsx}' and './components/**/*.{js,ts,jsx,tsx}'.
• Never Include CSS Files: Do not include your CSS files in the content paths. This can lead to infinite build loops.

How Tailwind Detects Classes

Tailwind does not parse or execute your code. It uses a regular expression to statically scan your files and find any string that looks like a Tailwind class. This has an important implication for how you write your classes.

The Golden Rule: Don’t Construct Class Names Dynamically

Because Tailwind scans for complete, unbroken class strings, you must avoid creating class names by concatenating strings. Tailwind needs to see the full class name in your source file to generate the corresponding CSS.

// A component that takes a color prop
function Alert({ color, children }) {

  // ❌ DON'T DO THIS: Tailwind will not find these classes
  const colorClass = `bg-${color}-500`; // e.g., 'bg-red-500'
  return <div className={colorClass}>{children}</div>;

  // ✅ DO THIS INSTEAD: Use a map to full class names
  const colorMap = {
    red: 'bg-red-500 text-red-100',
    blue: 'bg-blue-500 text-blue-100',
  };
  return <div className={colorMap[color]}>{children}</div>;

  // ✅ OR THIS: Let Ternaries choose between full class names
  return <div className={color === 'red' ? 'bg-red-500' : 'bg-blue-500'}>{children}</div>;
}

Advanced Configuration Options

Safelisting Classes

In rare cases, you might need to ensure certain classes are always included in your final CSS, even if they can’t be found in your content files (e.g., they are coming from a database). Use the safelist option for this. Use it sparingly, as it increases your final CSS bundle size.

tailwind.config.js

module.exports = {
  // ...
  safelist: [
    'bg-red-500',
    'bg-green-500',
    'bg-blue-500',
    { // You can also safelist patterns using regex
      pattern: /bg-(red|green|blue)-(100|200|300)/,
      variants: ['hover', 'focus'], // And include variants for them
    },
  ],
}

Styling Third-Party Libraries

If a third-party library renders HTML that you can’t add classes to directly, you have two main options:

• Target with CSS: Use @layer in your main CSS file to style the library’s selectors using @apply. This is the classic approach.
• Include Library Source: If the library’s source files are in your node_modules and contain Tailwind classes, you can add a path to them in your content configuration. This is common for “headless” UI libraries designed to be styled with Tailwind.

tailwind.config.js

const path = require('path');

module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    // Include classes from a headless UI library
    path.join(path.dirname(require.resolve('@headlessui/react')), '**/*.{js,ts,jsx,tsx}'),
  ],
  // ...
}

Troubleshooting Common Issues

• Classes Aren’t Working: The most common reason is a misconfigured content path. Double-check your glob patterns and file extensions. Make sure you’ve included all source directories.
• Styles Disappear in Production: If styles work in development but not in production, it’s almost always a content configuration issue. Your production build process is purging classes that it can’t find. Review the “Don’t Construct Class Names Dynamically” rule.
• Slow Build Times: If your build is slow, your content paths might be too broad. Avoid scanning node_modules or large directories that don’t contain any classes.