Core Code
Core Code Modern Dev Handbook

Configuration File (tailwind.config.js)

Content paths, theme extension, and safe defaults.
On this page

What tailwind.config.js Does

tailwind.config.js is the central place where you control how Tailwind generates utilities. In production, the most important part is the content list, because it defines which files Tailwind scans to detect classes.

Minimum working config

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{html,js}"],
  theme: {
    extend: {},
  },
  plugins: [],
};

The content key is not optional

If your content paths are wrong, Tailwind will not see your classes and your final CSS will be missing styles. This is the #1 production bug when Tailwind “does not work”.

Common content patterns

content: [
  "./*.php",
  "./public/**/*.php",
  "./src/**/*.{html,js,ts,jsx,tsx}",
]

Theme: defaults vs extension

Tailwind ships with a complete default design scale. In production, you usually extend the theme instead of replacing it. This keeps the ecosystem consistent while letting you add your own tokens.

Extend example

theme: {
  extend: {
    colors: {
      brand: {
        50: "#eef2ff",
        600: "#4f46e5",
      }
    },
    fontFamily: {
      sans: ["Inter", "ui-sans-serif", "system-ui"],
    }
  }
}

Why replacing theme can be dangerous

  • You may remove default utilities unintentionally.
  • Third-party Tailwind components often expect defaults.
  • You lose a stable baseline for spacing, sizing, and typography.

Plugins

Plugins add new utilities or components. Start minimal. Only add plugins when you are sure you need them.

Example plugin usage

plugins: [
  require('@tailwindcss/forms'),
  require('@tailwindcss/typography'),
]

Production checklist

  • content paths match your real templates (PHP, HTML, JS).
  • Theme changes are done via extend, not replacement.
  • Plugins are added intentionally, not by habit.
JIT Engine →