The postcss.config.js file

Listing plugins in every command is tedious, and -u cannot pass plugin options. So plugins are described in a postcss.config.js file in the project root. postcss-cli, Vite and other tools find it automatically.

Creating the file

Create postcss.config.js next to package.json:

blog/
├── postcss.config.js
├── styles/
│   └── main.css
└── package.json

The file exports an object with a plugins array. Each plugin is imported and called as a function:

// postcss.config.js
import autoprefixer from 'autoprefixer';
 
export default {
  plugins: [autoprefixer()],
};

The command gets shorter — the -u flag is no longer needed:

npx postcss styles/main.css -o css/main.css

The result in css/main.css is the same as in the previous lesson, but without the sourceMappingURL line: when a config file exists, source maps are turned on with its map option, covered in a separate lesson.

Plugin options

Options are passed as an argument when you call the plugin. For example, Autoprefixer has a cascade option: by default it aligns prefixed properties with spaces, and false turns the alignment off:

// postcss.config.js
import autoprefixer from 'autoprefixer';
 
export default {
  plugins: [autoprefixer({ cascade: false })],
};

.post-card {
  padding: 16px;
  -webkit-user-select: none;
  -moz-user-select: none;
  user-select: none;
}

The properties are no longer shifted to the right. Each plugin lists its options in its README.

Plugin order

Plugins run strictly in array order: the second one receives CSS already changed by the first. A typical sequence looks like this:

If cssnano runs first, the following plugins receive minified CSS, and whatever they add stays unminified.

Short form

You will also see a second form — an object where the key is the package name and the value is its options:

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

It works the same way, but the first form with import is clearer: you see where the plugin comes from, and the editor suggests its options. This course uses it.

Common mistake

Copying a CommonJS config from an old article — module.exports = ... and require(...) — into a project with "type": "module". The command fails with module is not defined in ES module scope. Either rewrite the file with import and export default, or rename it to postcss.config.cjs.