Introducing TailwindCSS v3 Support to Docusaurus v3

A Docusaurus has a label "TailwindCSS" for a painter. — Create by DALL.E 3

Recently, my side project adopted Docusaurus for building an easily deployable documentation site. Docusaurus is an impressive tool from the Facebook team. Our technology stack for this project includes TailwindCSS, so we opted to avoid using module CSS as our default CSS processor, mainly due to the fact that Docusaurus doesn't offer out-of-the-box support for TailwindCSS. In this blog, I will demonstrate how to implement TailwindCSS into your Docusaurus project.

Step 1: Setting Up Docusaurus

You can create a new project in a NodeJS environment by using the below command:

1npx create-docusaurus@latest website classic

Step 2: Installing TailwindCSS

As Docusaurus is built on top of React, you'd also need to include PostCSS and AutoPrefixer.

Use the following command to do so:

1pnpm i tailwindcss postcss autoprefixer -D

Next, create a tailwindcss.config.js file in the root of your Docusaurus project using this command:

1npx tailwindcss init

Then, append the source path to all your template files in the tailwind.config.js file.

1module.exports = {
2     content: ["./src/**/*.{js,jsx,ts,tsx}"],
3     theme: {
4         extend: {},
5     },
6    plugins: [],
7};

Step 3: Adding a Custom Plugin

Docusaurus's flexibility is underscored by its support for a plugin system. This system permits the use of TailwindCSS.

1 plugins: [
2    async function myPlugin() {
3      return {
4        name: 'docusaurus-tailwindcss',
5        configurePostCss(postcssOptions) {
6          // Appends TailwindCSS and AutoPrefixer.
7          postcssOptions.plugins.push(require('tailwindcss'));
8          postcssOptions.plugins.push(require('autoprefixer'));
9          return postcssOptions;
10        },
11      };
12    },
13  ],

Step 4: Loading TailwindCSS

This step entails slight modification of the src/css/custom.css file by adding the below segment at the top of this file:

1@tailwind base;
2@tailwind components;
3@tailwind utilities;

Step 5: Restart

Clear the Docusaurus cache and restart your project by using the following commands:

1pnpm clear
2pnpm start

After doing so, you can test TailwindCSS by modifying existing components.

Step 6*: Resolving Preflight Conflict

To resolve probable conflicts between TailwindCSS preflight styles and Docusaurus styles, add corePlugins: { preflight: false } to tailwind.config.js. However, if you wish to continue using TailwindCSS preflight while avoiding any conflict, update your Docusaurus plugin as follows:

1plugins: [
2    async function myPlugin() {
3      return {
4        name: 'docusaurus-tailwindcss',
5        injectHtmlTags() {
6          return {
7            headTags: [
8              {
9                tagName: 'link',
10                attributes: {
11                  rel: 'stylesheet',
12                  href: 'https://cdn.jsdelivr.net/npm/tailwindcss/dist/preflight.min.css',
13                },
14              },
15            ],
16          };
17        },
18        configurePostCss(postcssOptions) {
19          // Append TailwindCSS and AutoPrefixer.
20          postcssOptions.plugins.push(require('tailwindcss'));
21          postcssOptions.plugins.push(require('autoprefixer'));
22          return postcssOptions;
23        },
24      };
25    },
26  ],

Finally, TailwindCSS should now be perfectly integrated with Docusaurus. Happy coding!