PostCSS

8.5.13 verified Fri May 01 auth: no javascript

PostCSS is a CSS post-processor and syntax transformer that uses JavaScript plugins to parse and transform stylesheets. Stable version 8.x, actively maintained with monthly minor/patch releases. Key differentiators: plugin-driven architecture (over 200 plugins), supports future CSS syntax via plugins like postcss-preset-env, used by popular tools like Autoprefixer and Stylelint. Ships TypeScript definitions, supports ESM and CJS, requires Node.js 10+ (12+ for full features). Provides a fast CSS parser with source map support and a rich plugin API.

Common errors

error TypeError: Cannot read properties of undefined (reading 'type') ↓

cause Result from postcss().process() is a promise; forgot to await or use .then()

fix

Use await postcss([...]).process(css) or properly chain .then()

error Error: PostCSS plugin autoprefixer requires PostCSS 8. Update PostCSS or see: https://github.com/postcss/autoprefixer ↓

cause Incompatible plugin version with installed PostCSS major version

fix

Upgrade autoprefixer to 10.x for PostCSS 8: npm install autoprefixer@latest

error Error: Failed to find 'postcss' module ↓

cause PostCSS not installed or incorrectly referenced in package.json

fix

Run npm install postcss --save-dev

error TS2305: Module '"postcss"' has no exported member 'Root' ↓

cause Trying to import Root directly from 'postcss' instead of 'postcss/lib/root'

fix

Import Root from 'postcss/lib/root' or use postcss.parse() which returns a Root node

Warnings

breaking Node.js 14 or earlier is no longer supported for PostCSS 8.5.x ↓

fix Upgrade to Node.js 16+.

deprecated postcss().process() without a plugin array may behave unexpectedly ↓

fix Always pass an array of plugins: postcss([...]).process(css).

gotcha Using require('postcss') in CJS mode may cause TypeScript type inference issues ↓

fix Use import postcss from 'postcss' with esModuleInterop enabled in tsconfig.json.

gotcha PostCSS errors from plugins are not caught by default; unhandled promise rejections ↓

fix Wrap in try/catch or use .catch() on the promise returned by .process().

breaking The `sugarss` and `safe` parser options removed in v8 ↓

fix Use postcss-scss or postcss-syntax packages for non-standard syntax.

deprecated postcss.plugin() helper function deprecated ↓

fix Write plugins as functions directly: (root, result) => { ... }.

gotcha Source maps may be misaligned if 'from' and 'to' options are not provided consistently ↓

fix Always pass both 'from' and 'to' (or at least 'from') to .process().

Install

npm install postcss

yarn add postcss

pnpm add postcss

Imports

postcss
wrong
```
const postcss = require('postcss')
```
correct
```
import postcss from 'postcss'
```
Default import works for ESM and CJS. Since v8, Node.js can use require('postcss') but TypeScript may need esModuleInterop.
Root
wrong
```
import { Root } from 'postcss'
```
correct
```
import { Root } from 'postcss/lib/root'
```
Root is not directly exported from the main package; import from specific lib path or use postcss.parse().
Plugin
wrong
```
import { PluginCreator } from 'postcss'
```
correct
```
import { Plugin } from 'postcss'
```
Plugin is the type for creating PostCSS plugins. PluginCreator is internal; use Plugin.
Container
wrong
```
import { Node } from 'postcss'
```
correct
```
import { Container } from 'postcss'
```
Container is a base class for Root and AtRule; Node is not exported directly.

Quickstart

Shows basic PostCSS usage with Autoprefixer plugin: parse CSS, apply plugins, get output string.

import postcss from 'postcss';

const css = `
  .foo {
    color: red;
  }
`;

const result = await postcss([
  require('autoprefixer')({ overrideBrowserslist: ['last 2 versions'] })
]).process(css, { from: 'test.css' });

console.log(result.css);
// Output includes vendor prefixes if needed