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:

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.

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

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

/* 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:

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

File button.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:

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

Type Definitions

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

/* 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.

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