Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Tailwind CSS 4: the PostCSS plugin error and the v3 leftovers behind it

The moved PostCSS plugin is only half of it. Match the config extension, drop autoprefixer and postcss-import, and check for a second v3 copy.

~5 min readNext.js
#Tailwind CSS#Next.js#PostCSS#Migration
A CSS pipeline splitting one plugin block into two packages joined by a cyan bridge, amber outline on the old slot

Introduction & Quick Summary

Symptom. A Next.js dev server that has been running for months refuses to start after a dependency update, and the terminal prints a wall of PostCSS output rather than a compiler error:

code
⨯ ./app/globals.css Error: It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to continue using Tailwind CSS with PostCSS you'll need to install `@tailwindcss/postcss` and update your PostCSS configuration.

In Vite the same message arrives as [vite] Internal server error: Failed to load PostCSS config, sometimes preceded by Cannot find module 'tailwindcss'. On CI the build fails at the CSS step with exit code 1 and no mention of Tailwind at all.

Cause. In v3, the tailwindcss package was itself the PostCSS plugin. In v4 the engine, the PostCSS integration and the CLI are separate packages: tailwindcss, @tailwindcss/postcss and @tailwindcss/cli. A postcss.config.js that still lists tailwindcss: {} is asking the v4 engine to act as a plugin it no longer exports, so it throws this message on purpose. The dependency was upgraded; the config was not.

Fix. Install the plugin package and point the config at it, then delete the v3-era plugins the new one replaces:

bash
npm install tailwindcss @tailwindcss/postcss postcss npm uninstall autoprefixer postcss-import
js
// postcss.config.mjs export default { plugins: { "@tailwindcss/postcss": {}, }, };
css
/* app/globals.css */ @import "tailwindcss";

If the CSS still uses @tailwind base; @tailwind components; @tailwind utilities;, the build will produce no utilities even after the plugin error clears. That second failure is a separate one and is covered below.

Core Mechanics, Signatures & Reproducible Setup

Tailwind v4 is a Rust-based engine that reads CSS, not a JavaScript config. The PostCSS package is a thin adapter that hands your CSS to that engine during the bundler's CSS step. Because the adapter is a plugin object, it has to be referenced by its own package name:

js
// what v3 looked like module.exports = { plugins: { tailwindcss: {}, autoprefixer: {} } };
js
// what v4 needs export default { plugins: { "@tailwindcss/postcss": {} } };

Reproduce it without touching your project by installing both versions into a scratch directory:

bash
mkdir /tmp/tw4 && cd /tmp/tw4 npm init -y >/dev/null npm install tailwindcss@4 postcss postcss-cli printf '@import "tailwindcss";\n' > in.css printf 'export default { plugins: { tailwindcss: {} } };\n' > postcss.config.mjs npx postcss in.css -o out.css # prints the "moved to a separate package" error

Replace the config with "@tailwindcss/postcss": {} and the same command produces CSS. That is the entire diagnosis; everything else is a leftover from v3 or a framework-specific wiring mistake.

For Next.js specifically, there are two supported paths, and mixing them is a common cause of a config that appears to be ignored:

js
// next.config.ts — the plugin path, no postcss.config file needed import type { NextConfig } from "next"; const nextConfig: NextConfig = { experimental: { useLightningcss: true }, }; export default nextConfig;

In practice most Next.js projects keep PostCSS, because other plugins may be involved. In that case the file must be postcss.config.mjs (or .js with CommonJS syntax), and it must sit at the project root that Next.js resolves, not inside src/.

js
// postcss.config.js — CommonJS form, when the package is not type: module module.exports = { plugins: { "@tailwindcss/postcss": {}, }, };

Key Comparison Table

v3 usagev4 replacementNotes
tailwindcss as PostCSS plugin@tailwindcss/postcssseparate package, must be installed
npx tailwindcss init -pno init stepconfig is CSS-first
tailwind.config.js contentautomatic source detection, @sourceconfig file optional
@tailwind base/components/utilities@import "tailwindcss";the three directives are gone
theme.extend in JS@theme { --color-*: ... } in CSSdesign tokens are CSS variables
postcss-importbuilt inremove the plugin
autoprefixerbuilt in (Lightning CSS)remove the plugin
CLI from tailwindcss@tailwindcss/cliseparate package
safelist array@source inline(...)literal candidates in CSS
FrameworkCorrect v4 wiringCommon mistake
Next.js (PostCSS)@tailwindcss/postcss in postcss.config.mjsleaving tailwindcss: {} in place
Next.js (Lightning CSS)useLightningcss plus @import "tailwindcss"both paths configured at once
Vite@tailwindcss/vite in vite.config.tskeeping a PostCSS config that lists tailwindcss
Astro@tailwindcss/vite@astrojs/tailwind integration, removed in v4
Webpack / Rspack@tailwindcss/postcsspostcss.config.js with v3 keys
CLI onlynpx @tailwindcss/cli -i in.css -o out.cssnpx tailwindcss from v3 docs

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. The plugin error clears but no utilities are generated

After the config fix, a page renders unstyled with no error. The CSS entry still contains v3 directives, which v4 does not recognise as imports:

css
/* before */ @tailwind base; @tailwind components; @tailwind utilities;
css
/* after */ @import "tailwindcss";

Keep a single entry stylesheet per app and let it import the engine once. If you use @config "./tailwind.config.js" for legacy compatibility, that import must come after the engine import, not before it.

2. postcss.config.js is ignored in an ESM package

A package.json with "type": "module" makes a .js PostCSS config an ES module, so module.exports fails with ReferenceError: module is not defined in ES module scope. The message looks unrelated to Tailwind. Pick one form and keep the extension consistent with the package type:

js
// postcss.config.mjs — ESM export default { plugins: { "@tailwindcss/postcss": {} } };
js
// postcss.config.cjs — CommonJS inside a type: module package module.exports = { plugins: { "@tailwindcss/postcss": {} } };

Two config files in one directory is worse than either one: PostCSS loads the first it finds and silently ignores the other, so an edit to the ignored file appears to do nothing.

3. Sources are not scanned, so classes are missing

v4 detects sources relative to the CSS file and ignores paths in .gitignore, which is usually what you want. Monorepos and packages outside the app directory break that assumption, and the symptom is a page with most utilities present and a few missing:

css
@import "tailwindcss"; @source "../../packages/ui/src"; @source not "../legacy";
bash
# check what the engine actually scanned npx @tailwindcss/cli -i app/globals.css -o /tmp/out.css --debug

Dynamic class names built by string concatenation are still invisible to any scanner, which is the one place where an explicit @source inline("...") or a mapping object is the correct answer.

4. Next.js still serves a cached stylesheet

A dev server that has been running since before the upgrade can keep serving the old CSS chunk, so the fix looks ineffective. Clear the framework cache before concluding anything:

bash
rm -rf .next npm run dev

In a container or on Vercel, the build cache is the equivalent layer. A build that succeeds locally and fails remotely with the same message usually means the remote build still resolves an old postcss.config.js from a cached branch, or the lockfile was not updated with the new plugin.

5. Mixing v3 and v4 packages in a lockfile

npm ls tailwindcss answering with two versions is the most common cause of "I fixed it but the error is back". A transitive dependency can pull in tailwindcss@3, which reinstalls the v3 plugin shape:

bash
npm ls tailwindcss npm ls @tailwindcss/postcss npm dedupe

If a dependency genuinely pins v3, the honest options are to upgrade that dependency or to keep the whole project on v3 with tailwindcss@3 and the npx tailwindcss init workflow. Half-upgraded projects fail in ways that look random because which copy resolves depends on hoisting order.

6. Rolling back is a supported path

A large design system migration can reasonably take more than one sprint. v3 is still installable and documented, and a deliberate rollback beats a broken build:

bash
npm install tailwindcss@3 postcss autoprefixer npx tailwindcss init -p

Restore the three @tailwind directives and the content globs in that case, and remove @tailwindcss/postcss so the two engines cannot both claim the CSS step.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Leaving tailwindcss: {} in the PostCSS config. This is the error message's literal cause.
  • Installing @tailwindcss/postcss but not postcss. The adapter needs a PostCSS peer.
  • Keeping autoprefixer and postcss-import. v4 handles both; keeping them can reorder or duplicate output.
  • Editing tailwind.config.js and expecting v4 to read it. The CSS-first config is authoritative unless @config imports the old file.
  • Assuming content globs still decide what is scanned. Source detection replaced them.
  • Putting the PostCSS config inside src/. Next.js resolves it at the project root.
  • Shipping two config files with different extensions. One is loaded and the other is dead weight.
  • Upgrading the engine in a monorepo without upgrading the shared UI package. The UI package's build emits v3-shaped CSS.

When the tokens move into CSS variables, verify the palette you paste with the color converter; when a framework config is JSON, check it with the JSON formatter; and when comparing a working branch with a broken one, point the text diff tool at the two config files before guessing.

Reference: the Tailwind CSS v4 upgrade guide, installing Tailwind with PostCSS, and the Next.js framework guide.

Official references

primary documentation

The Next.js documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Next.js guides

More in Next.js

All Next.js guides

The guides filed next to this one in Next.js, in library order.