Custom Drupal Theme Development with Tailwind CSS v4

What You Need Before You Start

Make sure you have the following ready:

• A working Drupal 10+ site
• A custom Drupal theme (or you're ready to create one)
• Node.js and npm are installed on your system
• Basic understanding of Twig and Drupal theming

Step by Step Guide

Step 1: Create a Custom Theme (if you haven’t yet)

If you already have a custom theme, feel free to skip ahead. Otherwise, let’s create one quickly:

In themes/custom/ create a folder like:
Themes/custom/my_theme/

Now add the required files:

my_theme.info.yml
Name: My Theme
Type: theme
Base theme: classy
core_version_requirement: ^10
Libraries:
My_theme/tailwindcss
Regions:
Header: Header
Content: Content
Footer: Footer
my_theme.libraries.yml
tailwindcss:
  version: 1.x
  css:
    theme:
      css/styles.css: {}

Also, make sure you have a templates/ folder for your Twig files.

Step 2: Install Tailwind CSS v4 in Your Theme

Let’s now bring Tailwind into the theme using npm.

Open your terminal and run:

cd web/themes/custom/my_theme
npm init -y
npm install tailwindcss @tailwindcss/postcss postcss
npx tailwindcss init -p

This command will:

• Create tailwind.config.js for Tailwind setup
• Create postcss.config.js for processing CSS

Step 3: Configure Tailwind to Scan Drupal Files

Now open your tailwind.config.js file and update it like this:

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

This tells Tailwind to scan your Twig and YAML files for class names, so unused CSS can be purged automatically.

Step 4: Configure PostCSS for Tailwind

Now open your postcss.config.mjs file and update it like this:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  }
}

This sets up PostCSS to process Tailwind and add browser prefixes automatically.

Step 5: Create the Tailwind CSS Input File

Create a src/ folder inside your theme and add a file called styles.css:

web/themes/custom/my_theme/src/styles.css
Inside styles.css, add:
@import “tailwindcss”;

This file tells Tailwind what to include in your final compiled CSS.

Step 6: Compile Tailwind CSS

Now let’s build the CSS using Tailwind.
In your package.json, add this script:

"scripts": {
"build": "tailwindcss -i ./src/styles.css -o ./css/styles.css --watch"
}

Now run this command in your terminal:

npm run build

The css/styles.css file is generated in your theme, which is the file we referenced earlier in libraries.yml.

Step 7: Attach the Compiled CSS to Drupal

By now, your theme knows where to find the Tailwind CSS file.
Make sure your my_theme.libraries.yml looks like this:

tailwindcss:
version: 1.x
css:
  theme:
    css/styles.css: {}

Double-check your my_theme.info.yml to ensure the library is included:

libraries:
  my_theme/tailwindcss

Finally, clear the cache:

ddev drush cr

Or use the Drupal admin interface to clear the cache manually.

Step 8: Use Tailwind Classes in Your Twig Templates

Now you’re all set to use Tailwind in your templates!
Here’s an example in a Twig file like page.html.twig:

<div class="bg-indigo-700 text-white p-6 rounded-lg shadow-lg">
<h1 class="text-3xl font-bold">Welcome to My Tailwind-Powered Theme!</h1>
<p class="mt-2 text-sm">This is styled using Tailwind v4 classes inside a Drupal custom theme.</p>
</div>

You should now see the styling reflected immediately. Tailwind’s utility classes give you full control of padding, colors, borders, fonts, shadows, and much more. All without writing a line of custom CSS.

Bonus Tips for Tailwind v4 in Drupal

Here are some helpful tips to make your experience smoother:
Use @apply for reusable components:

.btn {
@apply px-4 py-2 bg-blue-600 text-white rounded;
}

Use Dark Mode:

Enable it in tailwind.config.js:
darkMode: 'class', // or 'media'

Optimize for production:

Tailwind v4 purges unused styles automatically in production mode:

NODE_ENV=production npm run build

Final Thoughts

By integrating Tailwind CSS v4 into your custom Drupal theme, you unlock a whole new level of productivity and design freedom. You can build beautiful, mobile-first layouts in minutes — no need to fight with custom CSS or bloated stylesheets.

Now you’re ready to build modern, clean, and maintainable Drupal themes using the power of Tailwind.

If this guide helped you, feel free to share it with your fellow developers, or leave a comment below, and I'd love to hear how you're using Tailwind in your Drupal projects!