How to Use Tailwind CSS v4 in Docusaurus Without Breaking Its Styles🦖

lukyn76 — Thu, 31 Jul 2025 16:48:20 +0000

Tailwind v4 is fast, powerful, and modern but if you're trying to use it in a Docusaurus site, you'll probably run into one major issue: Tailwind’s base styles (preflight) override Docusaurus’s own CSS.

This quick guide shows you how to install Tailwind CSS v4 into a Docusaurus project safely, so that Tailwind only affects your custom components, and doesn’t break the rest of your site.

✅ Step 1: Install Tailwind and PostCSS

Run the following in your project root:

npm install -D tailwindcss postcss @tailwindcss/postcss

✅ Step 2: Create a Docusaurus Plugin

Create a file at:

src/plugins/tailwind-config.js

Paste this inside:

module.exports = function tailwindPlugin(context, options) {
  return {
    name: "tailwind-plugin",
    configurePostCss(postcssOptions) {
      postcssOptions.plugins.push(require("@tailwindcss/postcss"));
      return postcssOptions;
    },
  };
};

💡 Important: We're using .push() instead of replacing the plugin list. This keeps other PostCSS features working (like Sass or autoprefixer).

✅ Step 3: Register the Plugin in `docusaurus.config.ts`

Open your docusaurus.config.ts and add the plugin:

plugins: ["./src/plugins/tailwind-config.js"],

✅ Step 4: Add Tailwind Imports to Your CSS

Edit src/css/custom.css and add the following:

@import "tailwindcss/theme.css" layer(theme);

@layer base {
  #tw-scope {
    @import "tailwindcss/preflight.css" layer(base);
  }
}

@import "tailwindcss/utilities.css" layer(utilities);

@custom-variant dark (&:is([data-theme="dark"] *));

✅ Step 5: Wrap Your Tailwind Components

Now, when building React components that use Tailwind, just wrap them with a container that has the id="tw-scope":

export default function MyComponent() {
  return (
    <div id="tw-scope">
      <div className="bg-blue-500 text-white p-4 rounded-lg">
        This part uses Tailwind CSS!
      </div>
    </div>
  );
}

💡 Why We Scope Preflight

Tailwind’s Preflight (its base layer of resets) applies global styles to elements like h1, button, a, etc. If left unscoped, it will override Docusaurus’s built-in theme and cause unexpected layout bugs.

By wrapping Preflight inside:

@layer base {
  #tw-scope {
    @import "tailwindcss/preflight.css" layer(base);
  }
}

…we ensure that Tailwind's resets only apply inside #tw-scope, keeping the rest of your Docusaurus site safe.

🧵 Final Thoughts

This setup lets you fully use Tailwind v4.1+ inside Docusaurus, but in a controlled way. You can design custom components, pages, or layouts with Tailwind without worrying about it interfering with Docusaurus styles.

If you found this useful, feel free to share it. Hopefully it saves others some hours of time :)

DEV Community: lukyn76