esbuild-plugin-tailwindcss

2.2.0 verified Mon Apr 27 auth: no javascript

esbuild plugin that integrates TailwindCSS into the build pipeline. Current stable version is 2.2.0, compatible with TailwindCSS v4. For TailwindCSS v3, use version 1.x. The plugin handles TailwindCSS processing via PostCSS, supports CSS Modules, custom PostCSS plugins, and Autoprefixer. It works with esbuild and Bun. Provides ESM and CJS exports with TypeScript type definitions.

Common errors

error Error: Cannot find module 'tailwindcss' ↓

cause Peer dependency tailwindcss is not installed.

fix

Install tailwindcss: npm install -D tailwindcss

error Error: @import "tailwindcss" not found ↓

cause Missing TailwindCSS import in CSS file.

fix

Add @import "tailwindcss"; at the top of your main CSS file.

error TypeError: plugin is not a function ↓

cause Attempted to use a named import incorrectly (e.g., import { tailwindPlugin } when using require).

fix

Use default import: import tailwindPlugin from 'esbuild-plugin-tailwindcss'

error Error: PostCSS plugin tailwindcss requires Tailwind Config ↓

cause TailwindCSS v4 expects a configuration file or proper setup; see TailwindCSS v4 migration.

fix

Create a tailwind.config.js or use TailwindCSS v4's new configuration approach (css-based).

Warnings

breaking Version 2.x requires TailwindCSS v4. Using with v3 will break. ↓

fix Use version 1.x for TailwindCSS v3: npm install esbuild-plugin-tailwindcss@^1.0.0

deprecated The 'options' object in the main function call was deprecated in v2 in favor of nested postcssPlugins and cssModules. ↓

fix Use new option structure: { postcssPlugins: { ... }, cssModules: { ... } }

gotcha CSS Modules: 'getJSON' callback is managed internally by the plugin. To get class mappings, listen to the 'css-modules' event on the plugin instance. ↓

fix Use the plugin's event emitter to capture class name mappings.

gotcha The @import "tailwindcss" statement must be in your CSS file; otherwise TailwindCSS is not processed. ↓

fix Add @import "tailwindcss"; to your main CSS file.

gotcha When using CSS Modules, the plugin will not process files that match the exclude regex. Non-matching files are left as-is. ↓

fix Ensure your CSS module files match the default /\\.module\\.css$/ pattern or adjust filter.

Install

npm install esbuild-plugin-tailwindcss

yarn add esbuild-plugin-tailwindcss

pnpm add esbuild-plugin-tailwindcss

Imports

default

wrong

const tailwindPlugin = require('esbuild-plugin-tailwindcss')

correct

import tailwindPlugin from 'esbuild-plugin-tailwindcss'

Plugin is exported as default export. Both ESM and CJS are supported.

tailwindPlugin (named)
```
import { tailwindPlugin } from 'esbuild-plugin-tailwindcss'
```
A named export 'tailwindPlugin' is also available, identical to default.

PluginOptions type

wrong

import { PluginOptions } from 'esbuild-plugin-tailwindcss'

correct

import type { PluginOptions } from 'esbuild-plugin-tailwindcss'

PluginOptions is a TypeScript type, use 'import type' for type-only imports.

Quickstart

Shows how to configure esbuild with the TailwindCSS plugin, including minimal options.

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

await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  bundle: true,
  plugins: [
    tailwindPlugin({
      postcssPlugins: {
        prepend: [],
        append: [],
        disableAutoprefixer: false
      },
      cssModules: {
        enabled: false
      }
    })
  ]
});