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.

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:
⨯ ./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:
npm install tailwindcss @tailwindcss/postcss postcss
npm uninstall autoprefixer postcss-import// postcss.config.mjs
export default {
plugins: {
"@tailwindcss/postcss": {},
},
};/* 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:
// what v3 looked like
module.exports = { plugins: { tailwindcss: {}, autoprefixer: {} } };// what v4 needs
export default { plugins: { "@tailwindcss/postcss": {} } };Reproduce it without touching your project by installing both versions into a scratch directory:
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" errorReplace 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:
// 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/.
// postcss.config.js — CommonJS form, when the package is not type: module
module.exports = {
plugins: {
"@tailwindcss/postcss": {},
},
};Key Comparison Table
| v3 usage | v4 replacement | Notes |
|---|---|---|
tailwindcss as PostCSS plugin | @tailwindcss/postcss | separate package, must be installed |
npx tailwindcss init -p | no init step | config is CSS-first |
tailwind.config.js content | automatic source detection, @source | config file optional |
@tailwind base/components/utilities | @import "tailwindcss"; | the three directives are gone |
theme.extend in JS | @theme { --color-*: ... } in CSS | design tokens are CSS variables |
postcss-import | built in | remove the plugin |
autoprefixer | built in (Lightning CSS) | remove the plugin |
CLI from tailwindcss | @tailwindcss/cli | separate package |
safelist array | @source inline(...) | literal candidates in CSS |
| Framework | Correct v4 wiring | Common mistake |
|---|---|---|
| Next.js (PostCSS) | @tailwindcss/postcss in postcss.config.mjs | leaving tailwindcss: {} in place |
| Next.js (Lightning CSS) | useLightningcss plus @import "tailwindcss" | both paths configured at once |
| Vite | @tailwindcss/vite in vite.config.ts | keeping a PostCSS config that lists tailwindcss |
| Astro | @tailwindcss/vite | @astrojs/tailwind integration, removed in v4 |
| Webpack / Rspack | @tailwindcss/postcss | postcss.config.js with v3 keys |
| CLI only | npx @tailwindcss/cli -i in.css -o out.css | npx 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:
/* before */
@tailwind base;
@tailwind components;
@tailwind utilities;/* 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:
// postcss.config.mjs — ESM
export default { plugins: { "@tailwindcss/postcss": {} } };// 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:
@import "tailwindcss";
@source "../../packages/ui/src";
@source not "../legacy";# check what the engine actually scanned
npx @tailwindcss/cli -i app/globals.css -o /tmp/out.css --debugDynamic 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:
rm -rf .next
npm run devIn 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:
npm ls tailwindcss
npm ls @tailwindcss/postcss
npm dedupeIf 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:
npm install tailwindcss@3 postcss autoprefixer
npx tailwindcss init -pRestore 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/postcssbut notpostcss. The adapter needs a PostCSS peer. - Keeping
autoprefixerandpostcss-import. v4 handles both; keeping them can reorder or duplicate output. - Editing
tailwind.config.jsand expecting v4 to read it. The CSS-first config is authoritative unless@configimports the old file. - Assuming
contentglobs 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 documentationThe Next.js documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Next.js guides
All Next.js guidesModule not found: Can't resolve a package or alias in Next.js
TypeScript and the bundler resolve imports separately. Align path aliases, workspace dependencies, exports conditions and filename case.
next/font: Failed to fetch a Google font during the build
The font is fetched during the build, not at runtime. Vendor it with next/font/local or give CI and Docker a route out.
Next.js cacheComponents: 'used uncached or runtime data' build error
Cache Components makes the build refuse to guess where the static shell ends. Stream it, cache it with use cache, or declare the route blocking.
Vercel 504: FUNCTION_INVOCATION_TIMEOUT
A serverless invocation has a wall-clock budget. Measure it, stream or defer the work, and raise maxDuration only where it is earned.
More in Next.js
All Next.js guidesThe guides filed next to this one in Next.js, in library order.