tailwind-drupal

CRITICAL RULE

Every time you add, modify, or remove Tailwind classes in ANY file (.twig, .html.twig, .php, .module, .theme), you MUST recompile the CSS and clear Drupal caches. Tailwind only includes classes it finds in scanned files. New classes that aren't compiled will NOT appear in the browser.

Mandatory post-change sequence

# 1. Recompile Tailwind CSS (ALWAYS after class changes)
ssh web npm run build --prefix $DDEV_DOCROOT/themes/custom/<THEME>

# 2. Clear Drupal cache (renders may reference old CSS)
ssh web drush cr

# 3. Verify in browser with hard refresh (Ctrl+Shift+R / Cmd+Shift+R)
#    Or use Playwright with cache disabled for testing

If you skip step 1, new Tailwind classes will NOT render. This is the most common cause of "Tailwind classes not working."

Installation in a Drupal theme

# Navigate to theme directory inside container
ssh web bash -c "cd $DDEV_DOCROOT/themes/custom/<THEME> && npm init -y"
ssh web bash -c "cd $DDEV_DOCROOT/themes/custom/<THEME> && npm install -D tailwindcss"
ssh web bash -c "cd $DDEV_DOCROOT/themes/custom/<THEME> && npx tailwindcss init"

Configuration files

package.json (in theme root)

{
  "scripts": {
    "dev": "npx tailwindcss -i ./src/input.css -o ./css/styles.css --watch",
    "build": "npx tailwindcss -i ./src/input.css -o ./css/styles.css --minify"
  },
  "devDependencies": {
    "tailwindcss": "^3.4"
  }
}

Script	Use	When
npm run dev	Watch mode, auto-recompile on file changes	During active development
npm run build	One-time compile + minify	Before commit, after changes

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  // NOTE: all content paths are relative to the THEME directory (where this file lives)
  content: [
    // Drupal theme templates
    './templates/**/*.html.twig',
    './components/**/*.html.twig',
    // Custom modules that use Tailwind classes
    '../../modules/custom/**/*.html.twig',
    '../../modules/custom/**/*.php',
    '../../modules/custom/**/*.module',
    // Theme PHP files (preprocess functions with class arrays)
    './*.theme',
  ],
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          100: '#dbeafe',
          200: '#bfdbfe',
          300: '#93c5fd',
          400: '#60a5fa',
          500: '#3b82f6',
          600: '#2563eb',
          700: '#1d4ed8',
          800: '#1e40af',
          900: '#1e3a8a',
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
    },
  },
  plugins: [],
}