DEV Community

Cover image for How to Use Tailwind CSS v4 in Docusaurus Without Breaking Its Styles🦖
lukyn76
lukyn76

Posted on • Edited on

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

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
Enter fullscreen mode Exit fullscreen mode

✅ 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;
    },
  };
};
Enter fullscreen mode Exit fullscreen mode

💡 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"],
Enter fullscreen mode Exit fullscreen mode

✅ 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"] *));
Enter fullscreen mode Exit fullscreen mode

✅ 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>
  );
}
Enter fullscreen mode Exit fullscreen mode

💡 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);
  }
}
Enter fullscreen mode Exit fullscreen mode

…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 :)

Top comments (0)