postcss

library8.5.13jsnpmunverified

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.

serialization devops

npm install postcss

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POSTCSS

postcss

serializationjavascriptv8.5.13

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

postcss

✓ import postcss from 'postcss'

✗ const postcss = require('postcss')

Default import works for ESM and CJS. Since v8, Node.js can use require('postcss') but TypeScript may need esModuleInterop.

Root

✓ import { Root } from 'postcss/lib/root'

✗ import { Root } from 'postcss'

Root is not directly exported from the main package; import from specific lib path or use postcss.parse().

Plugin

✓ import { Plugin } from 'postcss'

✗ import { PluginCreator } from 'postcss'

Plugin is the type for creating PostCSS plugins. PluginCreator is internal; use Plugin.

Container

✓ import { Container } from 'postcss'

✗ import { Node } from 'postcss'

Container is a base class for Root and AtRule; Node is not exported directly.

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

postcss --version

Debug

Known issues

breakingNode.js 14 or earlier is no longer supported for PostCSS 8.5.x

fix

Upgrade to Node.js 16+.

affects: >=8.5.0

deprecatedpostcss().process() without a plugin array may behave unexpectedly

fix

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

affects: >=8.0.0

gotchaUsing require('postcss') in CJS mode may cause TypeScript type inference issues

fix

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

affects: >=8.0.0

gotchaPostCSS 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().

affects: >=8.0.0

breakingThe `sugarss` and `safe` parser options removed in v8

fix

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

affects: >=8.0.0

deprecatedpostcss.plugin() helper function deprecated

fix

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

affects: >=8.0.0

gotchaSource 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().

affects: >=8.0.0

Errors

Common errors & fixes

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

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

fix

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

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

Incompatible plugin version with installed PostCSS major version

fix

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

Error: Failed to find 'postcss' module

PostCSS not installed or incorrectly referenced in package.json

fix

Run npm install postcss --save-dev

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

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

Upgrade

Version history

8.5.13latest on npm

Audit

Dependencies

postcss-value-parseroptionalUsed by many PostCSS plugins for parsing CSS values

postcss-selector-parseroptionalUsed by many PostCSS plugins for parsing selectors

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/postcss/postcss ↗

packagehttps://www.npmjs.com/package/postcss ↗

homepagehttps://postcss.org ↗