Tailwind CSS v4 PostCSS and Build Tools — Configuration Guide

Tailwind CSS v4 integrates with PostCSS, Vite, CLI, and other build tools. This guide covers configuring PostCSS, setting up build pipelines, and integrating with frameworks like Next.js, Remix, and Laravel.

What You'll Learn

You will learn how to configure PostCSS for Tailwind v4, integrate with major build tools, set up framework-specific configurations, and troubleshoot common build issues.

Why It Matters

A correct build configuration ensures Tailwind v4 generates optimized CSS, hot-reloads during development, and produces minimal bundles for production. DodaTech's v4 Migration reduced build time by 40 percent and configuration complexity by 60 percent.

Real-World Use

Doda Browser's frontend uses PostCSS with Tailwind v4 and the Vite plugin, delivering sub-8KB CSS bundles and sub-second rebuilds during development.

flowchart LR
    A[Source CSS] --> B[PostCSS]
    B --> C[Tailwind v4 Plugin]
    C --> D[Lightning CSS]
    D --> E[Optimized CSS]
    B --> F[Autoprefixer]
    B --> G[Other Plugins]
    style B fill:#38bdf8,stroke:#0284c7,color:#fff
    style D fill:#22c55e,stroke:#16a34a,color:#fff

PostCSS Configuration

// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
    autoprefixer: {},
  },
};

Expected output: This is the minimal PostCSS config for Tailwind v4. The @tailwindcss/postcss plugin replaces the v3 tailwindcss and autoprefixer combo.

/* app.css - entry point */
@import "tailwindcss";
@import "tailwindcss/theme" layer(theme);
@import "tailwindcss/preflight" layer(base);
@import "tailwindcss/utilities" layer(utilities);

@theme {
  --color-brand-500: #7c3aed;
}

Expected output: The @import "tailwindcss" statement loads the framework. Individual layer imports give finer control over CSS cascade ordering.

Vite Integration

// vite.config.js
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [tailwindcss()],
  build: {
    cssMinify: "lightningcss",
    minify: "esbuild",
    rollupOptions: {
      output: {
        manualChunks: undefined,
      },
    },
  },
});

Expected output: The @tailwindcss/vite plugin handles CSS processing. Setting cssMinify: "lightningcss" uses the same engine as Tailwind v4 for consistent output.

Framework Integration

// next.config.js — Next.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    optimizePackageImports: ["@tailwindcss/vite"],
  },
};

export default nextConfig;

Expected output: Next.js projects need the experimental config to optimize Tailwind v4 imports. The Vite plugin is automatically detected when using the Turbopack dev server.

// remix.config.js — Remix
/** @type {import('@remix-run/dev').AppConfig} */
export default {
  serverModuleFormat: "esm",
  tailwind: false, // Disable Remix's built-in Tailwind
  postcss: true,   // Use PostCSS with @tailwindcss/postcss
};

Expected output: Remix requires explicit PostCSS opt-in. Disable Remix's built-in Tailwind support and use the PostCSS plugin instead.

CLI Usage

# Install the standalone CLI
npm install -D @tailwindcss/cli

# Build CSS
npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css

# Watch mode
npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch

# Minified output
npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --minify

Expected output: The standalone CLI processes CSS files without a build tool. The --watch flag enables automatic rebuilds on file changes.

# Production build with environment variable
NODE_ENV=production npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --minify

Expected output: Setting NODE_ENV=production enables additional optimizations like unused variant removal.

Common Mistakes

1. Using Old tailwindcss Package

The v3 tailwindcss PostCSS plugin does not work with v4. Use @tailwindcss/postcss or @tailwindcss/vite instead.

2. Missing @import "tailwindcss"

In v4, you must @import "tailwindcss" in your CSS file. The @tailwind directives (@tailwind base, etc.) are removed.

3. Forgetting autoprefixer

Tailwind v4 uses Lightning CSS for vendor prefixes, but autoprefixer is still needed for non-Tailwind CSS. Include it in the PostCSS config.

4. Wrong Import Order

Custom @theme blocks, @import statements, and @layer directives must appear before Tailwind utilities are used. Order matters in CSS cascading.

5. Mixing PostCSS and Vite Plugin

Do not use both @tailwindcss/postcss and @tailwindcss/vite simultaneously. Choose one integration path to avoid duplicate processing.

Practice Questions

1. What is the difference between @tailwindcss/postcss and @tailwindcss/vite? PostCSS works with any PostCSS-compatible build tool. Vite plugin provides deeper Vite integration with HMR and optimized builds.

2. What replaces the old tailwindcss package in v4 PostCSS? @tailwindcss/postcss replaces tailwindcss as the PostCSS plugin.

3. How do you enable Minification in the CLI? Use the --minify flag: npx @tailwindcss/cli -i input.css -o output.css --minify.

4. What CSS @import is required in v4? @import "tailwindcss" is required. Layer-specific imports are optional.

5. Why set NODE_ENV=production during builds? It enables additional optimizations including unused variant removal and deeper CSS pruning.

Challenge

Set up a build pipeline for a multi-page project that uses PostCSS + Tailwind v4, includes autoprefixer, outputs minified CSS, and supports both development watch mode and production builds with environment variable control.

FAQ

Mini Project

Create a build configuration for a three-page marketing site. Use PostCSS with @tailwindcss/postcss and autoprefixer. Set up a package.json with dev (watch) and build (minified production) scripts. Include an @theme block with custom brand colors and fonts.

What's Next

Now master Responsive Utilities for building adaptive layouts across all device sizes. Then explore Animations for adding motion to your Tailwind v4 projects.