Fix PostCSS 'must export a plugins key' error in Next.js

I updated an old Next.js app and when I ran npm run dev I had this error:

error - ./node_modules/next/dist/build/webpack/loaders/css-loader/src/index.js??ruleSet[1].rules[2].oneOf[8].use[1]!./node_modules/next/dist/build/webpack/loaders/postcss-loader/src/index.js??ruleSet[1].rules[2].oneOf[8].use[2]!./styles/globals.css
Error: Your custom PostCSS configuration must export a `plugins` key.

I added a postcss.config.json file in the root of the project with this content:

{
  "plugins": []
}

and the app started working again.

Why does this error happen?

Next.js processes your CSS with PostCSS. Out of the box it uses its own default setup, which includes autoprefixer and a few CSS fixes for older browsers.

But if Next.js detects a custom PostCSS configuration in your project, it drops the defaults and uses yours instead. And it’s strict about the shape: the configuration must be an object with a plugins key.

The error tells you Next.js found a PostCSS configuration it can’t use. In my case it was an old app, and the leftover config didn’t match what the newer Next.js version expected.

The usual suspects:

• a postcss.config.js file that exports a function instead of an object
• a config with plugins loaded via require() instead of listed as strings
• a postcss key in package.json with the wrong shape

Next.js wants plugins declared as strings (or as ["plugin-name", { options }] pairs), because it needs to read the config without executing arbitrary code. A config that worked with plain webpack or another bundler can fail here.

Watch out when you need real plugins

My empty plugins array worked because that app didn’t use any PostCSS plugin. If your project uses Tailwind CSS, an empty array breaks your styles, because a custom config replaces the Next.js defaults entirely.

In that case list the plugins you need, as strings:

{
  "plugins": ["tailwindcss", "autoprefixer"]
}

Notice autoprefixer is in there too. Once you provide a custom configuration, Next.js no longer adds it for you, so you have to declare it yourself (and have it in your devDependencies).

If you’re unsure whether you need a custom config at all, try deleting the PostCSS config files and the postcss key from package.json. With no custom config present, Next.js falls back to its defaults and the error goes away.