rsbuild-plugin-tailwindcss

An Rsbuild plugin to integrate with Tailwind CSS V3.

Why?

Tailwind CSS is able to remove unused CSS classes through Content Configuration. However, its accuracy may be insufficient when:

• Using multiple entries
• Using a Tailwind CSS-based component library

This plugin uses the Rspack module graph to override the content configuration with imported modules, generating Tailwind CSS output based on usage.

Usage

Install:

npm add tailwindcss@3 rsbuild-plugin-tailwindcss -D

Add plugin to your rsbuild.config.ts:

// rsbuild.config.ts
import { pluginTailwindCSS } from 'rsbuild-plugin-tailwindcss';

export default {
  plugins: [pluginTailwindCSS()],
};

Custom Tailwind CSS Configuration

Create a tailwind.config.js file at the root of the project:

/** @type {import('tailwindcss').Config} */
export default {
  theme: {
    colors: {
      blue: '#1fb6ff',
      purple: '#7e5bef',
      pink: '#ff49db',
      orange: '#ff7849',
      green: '#13ce66',
      yellow: '#ffc82c',
      'gray-dark': '#273444',
      gray: '#8492a6',
      'gray-light': '#d3dce6',
    },
  },
};

This will be auto-loaded by Rsbuild and applied by rsbuild-plugin-tailwindcss.

[!NOTE]

You don't need to add content in the tailwind.config.js. rsbuild-plugin-tailwindcss will add the imported modules for you.

Custom PostCSS Options

Create a postcss.config.js file at the root of the project:

export default {
  plugins: {
    cssnano: process.env['NODE_ENV'] === 'production' ? {} : false,
  },
};

[!NOTE]

You don't need to add tailwindcss in the postcss.config.js. rsbuild-plugin-tailwindcss will add the plugin for you.

Or use the tools.postcss option in rsbuild.config.ts.

Options

config

• Type: string | undefined
• Default: tailwind.config.js

The path to custom Tailwind CSS configuration. Could be a relative path from the root of the project or an absolute path.

• Example:

// rsbuild.config.ts
import { pluginTailwindCSS } from 'rsbuild-plugin-tailwindcss';

export default {
  plugins: [
    pluginTailwindCSS({
      config: './config/tailwind.config.js',
    }),
  ],
};

exclude / include

• Type: ReadonlyArray<string | RegExp> | string | RegExp | null | undefined
• Default: undefined

These two options are used to filter which module to be processed by Tailwind CSS using picomatch pattern.

If include is omitted or empty, all modules that do not match any of the exclude patterns will be included. Otherwise, only modules that match one or more of the include patterns and do not match any of the exclude patterns will be included.

• Example:

Include all .js, .jsx, .ts, .tsx files but exclude files in ./src/store and node_modules:

// rsbuild.config.ts
import { pluginTailwindCSS } from '@byted-lynx/plugin-tailwindcss';

export default {
  plugins: [
    pluginTailwindCSS({
      include: /\.[jt]sx?/,
      exclude: ['./src/store/**', /[\\/]node_modules[\\/]/],
    }),
  ],
};

Note that picomatch patterns are very similar to minimatch patterns, and in most use cases, they are interchangeable. If you have more specific pattern matching needs, you can view this comparison table to learn more about where the libraries differ.

tailwindcssPath

Specifies the absolute path to the tailwindcss package.

By default, tailwindcss is resolved using Node.js module resolution algorithm starting from the root path.

This option allows explicit specification of the tailwindcss package location for scenarios where automatic resolution fails or the resolved path is not correct, such as in monorepo.

• Type: string | undefined
• Default: undefined

// rsbuild.config.ts
import { pluginTailwindCSS } from 'rsbuild-plugin-tailwindcss';

export default {
  plugins: [
    pluginTailwindCSS({
      tailwindcssPath: require.resolve('tailwindcss'),
    }),
  ],
};

Debugging

Use DEBUG='rsbuild' to enable debugging mode for the plugin. When debugging is enabled, the plugin will:

1. Save the generated Tailwind CSS configuration files in the .rsbuild/<entry-name> directory inside your project's output path.
2. Generate readable configuration files that include all modules being processed by Tailwind CSS.

This is helpful for:

• Inspecting which modules are included in the Tailwind CSS content scanning
• Troubleshooting issues with CSS purging
• Understanding how the plugin is generating configurations for each entry point

Example:

# For macOS/Linux
DEBUG=rsbuild npm run build

# For Windows (cmd)
set DEBUG=rsbuild && npm run build

# For Windows (PowerShell)
$env:DEBUG="rsbuild"; npm run build

You can also use more specific debug patterns:

• DEBUG=rsbuild:tailwind - Debug only the Tailwind CSS plugin
• DEBUG=rsbuild:* - Debug all Rsbuild plugins
• DEBUG=* - Debug everything

Credits

Thanks to:

• Tailwind CSS V4 for the idea of purge CSS by module graph.
• The purge-tailwind-plugin created by @hardfist for the implementation of the Rspack plugin.
• The Rollup project created by Rich Harris and maintained by Lukas Taegert-Atkinson for the implementaion of exclude and include.

License

MIT.