esbuild-plugin-tailwindcss

Just a esbuild plugin to simplify the connection of TailwindCSS.


> [!NOTE]
> This version (2.x) works with TailwindCSS v4. If you need TailwindCSS v3, use the 1.x version of this plugin.

Install

| Package manager | Command |
| --------------- | ---------------------------------------- |
| npm | npm i -D esbuild-plugin-tailwindcss |
| yarn | yarn add -D esbuild-plugin-tailwindcss |
| bun | bun add -d esbuild-plugin-tailwindcss |

Basic usage

> This module can be imported as ESM or CJS. The examples below use the ESM syntax.

Add plugin in build config:

``js
import esbuild from 'esbuild';
import tailwindPlugin from 'esbuild-plugin-tailwindcss';

esbuild.build({
entryPoints: ['src/index.js'],
outdir: 'dist',
bundle: true,
plugins: [
tailwindPlugin({ / options / }),
],
});
`

Add the @import "tailwindcss" import to your main CSS file.

`css
/ index.css /
@import 'tailwindcss';
`

Import index.css from your main js, jsx, ts, tsx file:

`js
/ index.js /
import './index.css';
`

Done, you can use the TailwindCSS in the project!

Options

| Name | Type | Default | Description |
| ------------------------ | ----------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| postcssPlugins.prepend | PostcssPlugin[] | [] | Adds custom PostCSS plugins before TailwindCSS processing. |
| postcssPlugins.append | PostcssPlugin[] | [] | Adds custom PostCSS plugins after TailwindCSS processing. |
| cssModules.enabled | boolean | false | Enables CSS Modules support. When enabled, class names are locally scoped by default, meaning they are unique to the component and won't conflict with other styles. |
| cssModules.filter | RegExp | /\.module\.css$/ | A regular expression to detect which files should be processed as CSS Modules. |
| cssModules.exclude | RegExp[] | [] | An array of regular expressions to exclude specific files or paths from CSS Modules processing. |

CSS Modules

If the cssModules.enabled option is true, you can use css modules with TailwindCSS. For example:

File button.module.css:

`css
.button {
@apply px-4 py-2 border-2 rounded;
background: #faf;
}
`

File button.jsx:

`jsx
import styles from './button.module.css';

export const Button = ({ label }) => {
return {label};
};
`

To make css modules work more correctly, add the main CSS file to the excludes:

`js
tailwindPlugin({
cssModules: {
enabled: true,
exclude: ['index.css']
}
}),
`

Type Definitions

To avoid TypeScript errors when importing CSS, add the types to your global declaration file:

`ts
/ globals.d.ts /

declare module '*.module.css' {
const classes: Record;
export default classes;
}
`

Using with Bun

Since Bun's bundler API is compatible with esbuild, this module can be used as a Bun plugin.

`ts
Bun.build({
plugins: [
tailwindPlugin({ / pass plugin options here / }),
]
})
``