PostCSS Plugin

The @tailwindcss/postcss plugin allows you to integrate Tailwind CSS into any build tool that supports PostCSS, including Next.js, webpack, Parcel, and more.

Installation

Install the plugin

Install the @tailwindcss/postcss package:

npm install -D @tailwindcss/postcss

pnpm add -D @tailwindcss/postcss

yarn add -D @tailwindcss/postcss

bun add -D @tailwindcss/postcss

Configure PostCSS

Add the plugin to your postcss.config.js:

postcss.config.js

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Or using ES modules:

postcss.config.mjs

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Import Tailwind in your CSS

Add the Tailwind CSS import to your main CSS file:

src/styles.css

@import 'tailwindcss';

Configuration

The PostCSS plugin accepts several configuration options:

postcss.config.js

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {
      base: './src',
      optimize: true,
      transformAssetUrls: true,
    },
  },
}

Options

string

The base directory to scan for class candidates.Default: process.cwd() (current working directory)

boolean | { minify?: boolean }

Enable CSS optimization and minification.

false - No optimization
true - Full optimization with minification
{ minify: false } - Optimize without minifying

Default: true when NODE_ENV === 'production', otherwise false

boolean

Enable or disable asset URL rewriting for relative paths.Default: true

How It Works

The PostCSS plugin processes your CSS in the PostCSS pipeline:

Detects Tailwind CSS - Identifies files that use Tailwind directives
Parses CSS - Converts PostCSS AST to Tailwind’s internal AST
Compiles utilities - Generates CSS for detected Tailwind classes
Scans content - Finds all Tailwind classes in your source files
Optimizes - Optionally minifies the output using Lightning CSS
Returns CSS - Converts back to PostCSS AST for further processing

Caching

The plugin uses intelligent caching to speed up rebuilds:

Compiler cache - Reuses the compiler instance when possible
Scanner cache - Maintains a list of scanned files
CSS cache - Avoids regenerating unchanged CSS
Optimization cache - Caches optimized output

The cache is automatically invalidated when:

CSS files are modified
Configuration files change
Plugin files are updated
Template files are added or removed

Dependency Tracking

The plugin automatically tracks dependencies and reports them to PostCSS:

// Dependencies are reported for:
- CSS files imported with @import
- JavaScript configuration files
- Plugin files
- All scanned content files

This ensures your build tool rebuilds when any relevant file changes.

Content Detection

The plugin automatically scans your project for Tailwind classes:

// Default pattern:
**/*

// From the base directory

Customize content sources using the @source directive:

@import 'tailwindcss';
@source '../templates/**/*.html';
@source './components/**/*.jsx';

Integration Examples

Next.js

postcss.config.js

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Then import your CSS in _app.js or layout.js:

app/layout.js

import './globals.css'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

Webpack

With css-loader and postcss-loader:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          'postcss-loader', // Will use postcss.config.js
        ],
      },
    ],
  },
}

Parcel

Parcel automatically detects postcss.config.js. Just import your CSS:

src/index.js

import './styles.css'

Laravel Mix

webpack.mix.js

const mix = require('laravel-mix')

mix
  .postCss('resources/css/app.css', 'public/css', [
    require('@tailwindcss/postcss'),
  ])

PostCSS Import

The plugin works seamlessly with postcss-import:

postcss.config.js

module.exports = {
  plugins: {
    'postcss-import': {},
    '@tailwindcss/postcss': {},
  },
}

This allows you to split your CSS into multiple files:

styles.css

@import './base.css';
@import './components.css';
@import './utilities.css';

The plugin automatically fixes relative paths when files are imported, ensuring asset URLs remain correct.

Optimization

Development

Disable optimization for faster builds:

postcss.config.js

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {
      optimize: false,
    },
  },
}

Production

Enable optimization with minification:

postcss.config.js

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {
      optimize: process.env.NODE_ENV === 'production',
    },
  },
}

Optimize Without Minification

postcss.config.js

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {
      optimize: {
        minify: false,
      },
    },
  },
}

CSS Modules

The plugin automatically detects CSS Module files (*.module.css) and disables the @property polyfill to avoid build errors with non-pure selectors.

Button.module.css

@import 'tailwindcss';

.button {
  @apply px-4 py-2 bg-blue-500 text-white rounded;
}

Rebuild Strategies

The plugin uses two rebuild strategies:

Incremental Rebuild

When only template files change:

Scans changed files for new candidates
Rebuilds CSS only if new classes are found
Very fast, typically under 10ms

Full Rebuild

When CSS, config, or plugin files change:

Clears the require cache
Recreates the compiler
Scans all content files
Rebuilds the entire CSS output

The plugin uses an AST-to-AST transformation between PostCSS and Tailwind’s internal representation for optimal performance.

Troubleshooting

Changes Not Detected

If your build tool isn’t detecting changes:

Ensure your build tool is configured to watch CSS files
Check that dependency messages are being processed
Verify the base option points to the correct directory

Slow Builds

For large projects:

Use specific content patterns with @source
Exclude unnecessary directories (like node_modules)
Disable optimization in development
Consider using the Vite plugin for better performance

Import Errors

If you see import-related errors:

Ensure postcss-import runs before @tailwindcss/postcss
Check that all imported files exist
Verify relative paths are correct

Getting Started

Core Concepts

Customization

Build Integration

Advanced

Upgrading

Installation

Configuration

Options

How It Works

Caching

Dependency Tracking

Content Detection

Integration Examples

Next.js

Webpack

Parcel

Laravel Mix

PostCSS Import

Optimization

Development

Production

Optimize Without Minification

CSS Modules

Rebuild Strategies

Incremental Rebuild

Full Rebuild

Troubleshooting

Changes Not Detected

Slow Builds

Import Errors

​Installation

​Configuration

​Options

​How It Works

​Caching

​Dependency Tracking

​Content Detection

​Integration Examples

​Next.js

​Webpack

​Parcel

​Laravel Mix

​PostCSS Import

​Optimization

​Development

​Production

​Optimize Without Minification

​CSS Modules

​Rebuild Strategies

​Incremental Rebuild

​Full Rebuild

​Troubleshooting

​Changes Not Detected

​Slow Builds

​Import Errors

Installation

Configuration

Options

How It Works

Caching

Dependency Tracking

Content Detection

Integration Examples

Next.js

Webpack

Parcel

Laravel Mix

PostCSS Import

Optimization

Development

Production

Optimize Without Minification

CSS Modules

Rebuild Strategies

Incremental Rebuild

Full Rebuild

Troubleshooting

Changes Not Detected

Slow Builds

Import Errors