esbuild-tailwind-ssr-plugin

0.1.25 verified Fri May 01 auth: no javascript

An esbuild plugin for compiling Tailwind CSS, version 0.1.25. It integrates Tailwind CSS into esbuild builds, supporting server-side rendering (SSR) and CSS modules. The plugin is part of the Goldstack monorepo and is designed to work with esbuild's plugin system, allowing Tailwind CSS processing during bundling. It is actively maintained with regular releases. Key differentiators include native esbuild integration, SSR support, and compatibility with CSS modules.

Common errors

error Error: [esbuild-tailwind-ssr-plugin] Tailwind CSS not found. Please install tailwindcss. ↓

cause Missing peer dependency 'tailwindcss'.

fix

Run 'npm install tailwindcss' or 'yarn add tailwindcss'.

error TypeError: Cannot destructure property 'config' of 'undefined' as it is undefined. ↓

cause Plugin options object not passed correctly.

fix

Ensure you pass an options object to 'esbuildTailwindSSRPlugin({...})'.

error Error: Could not resolve 'tailwindcss' when bundling with esbuild. ↓

cause Tailwind CSS not installed or not in node_modules.

fix

Install tailwindcss and ensure it is listed in package.json dependencies.

error Error: The 'content' path './src/**/*.{ts,tsx}' does not match any files. ↓

cause Incorrect glob pattern in Tailwind config.

fix

Adjust 'content' pattern to match your source files, e.g., ['./src/**/*.{js,jsx,ts,tsx}'].

Warnings

breaking Plugin requires esbuild v0.9 or higher; older versions not supported. ↓

fix Upgrade esbuild to version 0.9 or higher.

gotcha The plugin outputs CSS as a separate file; it does not inline styles into JavaScript. ↓

fix Ensure your HTML references the output CSS file.

deprecated Option 'cssModules' is deprecated; use 'cssModules' in plugin options instead. ↓

fix Move 'cssModules' configuration under the plugin options object.

gotcha Tailwind CSS v3+ is required; v2 is not supported. ↓

fix Upgrade to Tailwind CSS v3 or later.

Install

npm install esbuild-tailwind-ssr-plugin

yarn add esbuild-tailwind-ssr-plugin

pnpm add esbuild-tailwind-ssr-plugin

Imports

esbuildTailwindSSRPlugin

wrong

const esbuildTailwindSSRPlugin = require('esbuild-tailwind-ssr-plugin')

correct

import { esbuildTailwindSSRPlugin } from 'esbuild-tailwind-ssr-plugin'

ESM-only; does not support CommonJS require.

default

wrong

import { default as esbuildTailwindSSRPlugin } from 'esbuild-tailwind-ssr-plugin'

correct

import esbuildTailwindSSRPlugin from 'esbuild-tailwind-ssr-plugin'

Default export is the same as named export.

PluginOptions

wrong

import { PluginOptions } from 'esbuild-tailwind-ssr-plugin'

correct

import type { PluginOptions } from 'esbuild-tailwind-ssr-plugin'

PluginOptions is a TypeScript type, not a runtime value.

Quickstart

Demonstrates basic usage of the esbuild Tailwind CSS plugin with custom Tailwind configuration.

import { build } from 'esbuild';
import { esbuildTailwindSSRPlugin } from 'esbuild-tailwind-ssr-plugin';

await build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    esbuildTailwindSSRPlugin({
      inputCSS: 'src/styles.css',
      outputCSS: 'dist/styles.css',
      tailwindConfig: {
        content: ['./src/**/*.{ts,tsx}'],
      },
    }),
  ],
});