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/

# 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/ && npm init -y"
ssh web bash -c "cd $DDEV_DOCROOT/themes/custom/ && npm install -D tailwindcss"
ssh web bash -c "cd $DDEV_DOCROOT/themes/custom/ && 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: [],
}

CRITICAL: The content array must include ALL file paths where Tailwind classes appear. If a file is not scanned, its classes are purged from the compiled CSS.

src/input.css

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Custom component classes (use @apply sparingly) */
@layer components {
  .btn-primary {
    @apply inline-flex items-center px-4 py-2 text-sm font-medium text-white bg-primary-600 hover:bg-primary-700 rounded-lg transition-colors focus:outline-none focus:ring-2 focus:ring-primary-500 focus:ring-offset-2;
  }
}

Drupal library definition (mytheme.libraries.yml)

tailwind:
  css:
    theme:
      css/styles.css: { minified: true }

Attach in your base template (e.g., html.html.twig or page.html.twig):

{{ attach_library('mytheme/tailwind') }}

Build commands

# Development: watch mode (auto-recompiles on save)
ssh web npm run dev --prefix $DDEV_DOCROOT/themes/custom/

# Production: one-time build with minification
ssh web npm run build --prefix $DDEV_DOCROOT/themes/custom/

# After build, ALWAYS clear Drupal cache
ssh web drush cr

Responsive breakpoints

| Prefix | Min-width | Use for | |--------|-----------|---------| | (none) | 0px | Mobile first (default) | | sm: | 640px | Small tablets | | md: | 768px | Tablets | | lg: | 1024px | Desktops | | xl: | 1280px | Large screens | | 2xl: | 1536px | Extra large |

Always design mobile-first: write base styles without prefix, then add breakpoint prefixes for larger screens.

Troubleshooting

| Problem | Cause | Fix | |---------|-------|-----| | Classes not rendering | CSS not recompiled | npm run build → drush cr → hard refresh | | Classes purged in prod | File path missing from content array | Add path to tailwind.config.js content | | Styles cached in browser | Browser using old CSS | Hard refresh (Ctrl+Shift+R) or clear browser cache | | Classes in PHP not found | .php/.module/.theme files not in content | Add '../../modules/custom/**/*.php' to content | | Watch mode not detecting | File outside content paths | Add missing glob pattern to content array | | @apply not working | Custom class not in @layer | Wrap in @layer components { } | | npm run build fails | Missing node_modules | ssh web npm install --prefix $DDEV_DOCROOT/themes/custom/ then rebuild | | npm: command not found | Command run in wrong container | Prefix the command with ssh web |

Verification

After ANY Tailwind class change:

# 1. Build
ssh web npm run build --prefix $DDEV_DOCROOT/themes/custom/

# 2. Verify the compiled file exists AND contains the new class (replace CLASS):
ssh web test -f $DDEV_DOCROOT/themes/custom//css/styles.css && echo "FILE OK"
ssh web grep -c "CLASS" $DDEV_DOCROOT/themes/custom//css/styles.css
# Output 0 or "FILE OK" missing → build failed or class not in a scanned path (check content array)

# 3. Clear Drupal cache
ssh web drush cr

# 4. Test in browser (use Playwright or hard refresh)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: trebormc
• Source: trebormc/drupal-ai-agents
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.