Tailwind Configuration

What Is the Tailwind Configuration File?

tailwind.config.js is a JavaScript module that exports an object describing your project's design tokens and behavior: which files to scan (content), your design scale (theme), and any plugins to load.

Tailwind v4 introduces an alternative CSS-first configuration approach using @theme blocks directly in your CSS file, reducing the need for a separate JavaScript config file in many projects.

/** @type {import('tailwindcss').Config} */
export default {
  content: ["./src/**/*.{html,js,astro}"],
  theme: {
    extend: {
      colors: {
        brand: "#1d4ed8",
      },
    },
  },
  plugins: [],
};

This config scans the src folder for classes and adds one custom color, brand, on top of the default palette.

Configuration File Structure

export default {
  content: [...],
  theme: {
    extend: { ... },
  },
  plugins: [...],
};

• content lists file globs Tailwind scans to find used class names.
• theme defines your design tokens; theme.extend adds to the defaults instead of replacing them.
• plugins registers additional functionality, like @tailwindcss/forms or @tailwindcss/typography.
• Top-level theme keys (without extend) fully replace Tailwind's built-in defaults for that key.

Configuration Cheatsheet

Key configuration options and what they control.

theme.extend vs Replacing theme Directly

Adding keys directly under theme (like theme.colors) completely replaces Tailwind's default value for that key, losing every built-in color. Adding the same keys under theme.extend merges your additions with the defaults instead, which is what most projects want.

// Replaces the ENTIRE default color palette, losing blue, red, etc.
theme: {
  colors: { brand: "#1d4ed8" },
},

// Adds "brand" alongside all existing default colors
theme: {
  extend: {
    colors: { brand: "#1d4ed8" },
  },
},

Writing Correct Content Globs

The content array uses glob patterns to find every file where Tailwind classes might appear. Missing a file type here is the single most common cause of "my classes aren't working" bugs in a real project.

content: [
  "./index.html",
  "./src/**/*.{js,jsx,ts,tsx,vue,astro,svelte}",
],

Every framework-specific file extension your project actually uses should be listed explicitly.

CSS-Based Configuration in Tailwind v4

Tailwind v4 lets you define design tokens directly inside your CSS using an @theme block, reducing (though not always eliminating) the need for a separate JavaScript config file for simpler customizations.

@import "tailwindcss";

@theme {
  --color-brand: #1d4ed8;
  --spacing-128: 32rem;
}

This automatically generates utilities like bg-brand, text-brand, and w-128, matching the JS-config equivalent.

Common Mistakes

• Adding custom values directly under theme instead of theme.extend, accidentally deleting all default values for that key.
• Forgetting to add a file extension to content, silently dropping classes used only in that file type from the final build.
• Not restarting the dev server after changing the configuration file, missing new classes during development.
• Mixing Tailwind v3 JS config patterns with v4-only CSS @theme syntax inconsistently after an incomplete migration.
• Overwriting the entire default screens object when only one breakpoint needed to change, instead of using extend.

Key Takeaways

• tailwind.config.js controls content scanning, theme customization, and plugins.
• theme.extend merges new values with Tailwind's defaults; top-level theme keys replace them entirely.
• Content globs must include every file extension your project uses Tailwind classes in.
• Tailwind v4 supports CSS-based configuration through @theme blocks as an alternative to the JS config file.
• Configuration changes typically require restarting the dev server to take effect.