Tailwind CSS Config Reference

What every tailwind.config.js key does

A tailwind.config.js file customises the design tokens, scanned files and build behaviour of Tailwind CSS. This reference lists the top-level configuration keys with their value type and purpose, and explains the crucial theme versus theme.extend distinction, searchable by key name.

How Tailwind’s build pipeline uses the config

At build time Tailwind:

1. Loads your config file (or uses defaults if there is none).
2. Resolves the complete theme by merging your theme.extend values on top of the built-in defaults.
3. Scans every file matched by your content globs for class name strings.
4. Generates only the CSS utilities it found — nothing else.

Because of step 4, the content key is the most important one to get right. A missing path means entire pages of classes are absent from your production bundle, causing invisible failures that only appear after deployment.

A minimal but real config

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{html,js,ts,jsx,tsx}"],
  darkMode: "class",
  theme: {
    extend: {
      colors: { brand: "#0a7" },
      spacing: { 18: "4.5rem" },
    },
  },
  plugins: [require("@tailwindcss/forms")],
};

Values under theme.extend are merged on top of the defaults, while values placed directly under theme replace a default scale. prefix, important and darkMode tune output; plugins registers extra utilities.

The theme vs. theme.extend distinction

This is the single most common source of confusion in Tailwind configs:

Unless you deliberately want to wipe a scale (rare — for example, enforcing a strict design token set), always use extend.

Common mistakes and fixes

Classes disappear in production but work locally. Almost always a content glob that misses a file type or directory. For example, forgetting to add .mdx when you have MDX pages, or missing a component library path. Check that every file containing Tailwind class names is matched by at least one glob entry.

darkMode toggle does nothing. If you set darkMode: "class" but the dark class is never added to html or body, the dark variants never fire. You need JS to toggle it; the config only tells Tailwind which strategy to use.

Conflicting CSS when Tailwind is used alongside a third-party library. Use prefix: "tw-" so every Tailwind utility becomes tw-flex, tw-text-sm, etc., and add important: '#app' if you need Tailwind utilities to always win specificity battles inside a certain selector.

Key reference at a glance

This reference targets Tailwind CSS v3 JS config. Tailwind v4 moves design tokens into CSS @theme blocks, but the concepts of theme vs. extend and content scanning carry over.