esbuild-plugin-tailwindcss/readme.md

Esbuild plugin for TailwindCSS

# esbuild-plugin-tailwindcss

Just a [esbuild](https://esbuild.github.io/) plugin to simplify the connection of [TailwindCSS](https://tailwindcss.com).

[![npm](https://img.shields.io/npm/v/esbuild-plugin-tailwindcss.svg)](https://www.npmjs.com/package/esbuild-plugin-tailwindcss)
[![npm](https://img.shields.io/npm/dt/esbuild-plugin-tailwindcss.svg)](https://www.npmjs.com/package/esbuild-plugin-tailwindcss)
[![npm](https://img.shields.io/npm/l/esbuild-plugin-tailwindcss.svg)](https://www.npmjs.com/package/esbuild-plugin-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 <button className={styles.button}>{label}</button>;
};
```

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<string, string>;
  export default classes;
}
```

## Using with Bun

Since Bun's bundler API is compatible with esbuild, this module can be used as a [Bun plugin](https://bun.sh/docs/bundler/plugins).

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