postcss

PostCSS parses CSS into an abstract syntax tree and exposes that tree to a pipeline of JavaScript plugins, each free to inspect or rewrite rules, declarations, and at-rules before the result is stringified back to CSS. It doesn’t impose its own syntax the way a preprocessor like Sass does — it works with real CSS (and CSS-like syntaxes via pluggable parsers) and lets the plugin ecosystem, not the core, decide what transformations happen.

That plugin model has made PostCSS the shared foundation underneath more than 200 published plugins, including Autoprefixer for vendor prefixing and Tailwind CSS’s own processing pipeline. The core ships as a small, dependency-light library (three runtime dependencies) with hand-maintained TypeScript type definitions, 100%-enforced test coverage, and a decade-old plugin contract that has stayed stable enough for that whole ecosystem to build on top of it without breaking changes.

What You Get

• A stable, class-based CSS AST (Root/Rule/AtRule/Declaration/Comment) with walk* traversal helpers for writing your own transformations.
• A processing pipeline (postcss(plugins).process(css)) that supports both synchronous and asynchronous plugins.
• Built-in source map generation and consumption for tracing transformed CSS back to its original source.
• Typed CSS syntax errors with optional terminal-highlighted output pointing at the exact source location of a parse failure.

Common Use Cases

• Running Autoprefixer, Tailwind CSS, or cssnano — all of which are PostCSS plugins under the hood.
• Writing a custom lint rule or codemod that needs to inspect or rewrite CSS programmatically.
• Parsing non-standard CSS-like syntaxes (Sass, Less, CSS-in-JS template literals) via one of PostCSS’s pluggable syntax parsers.

Under The Hood

Architecture PostCSS splits CSS processing into three explicit stages: a tokenizer (lib/tokenize.js) that turns a raw CSS string into a flat token stream, a parser (lib/parser.js) that assembles those tokens into a class-based AST rooted at a Root node with Rule/AtRule/Declaration/Comment children, and a stringifier that walks the same AST back into CSS text. Plugins operate entirely on the AST between the parse and stringify stages, using walkDecls/walkRules/walkAtRules traversal helpers inherited from a shared Container base class. This split — the project’s own architecture documentation explicitly justifies it on performance and readability grounds — is what lets a decade of downstream plugins (Autoprefixer, cssnano, postcss-nested, and 200+ others) share one stable core without needing to write their own parser.

Tech Stack The runtime is plain, unbundled JavaScript published directly to npm, with dual CommonJS/ESM entry points declared via package.json’s exports map. TypeScript is used only for the test suite (via ts-node) and for hand-authored .d.ts type declarations shipped alongside the JS — there is no build-time compilation step for the library itself. Runtime dependencies are deliberately minimal: nanoid for identifier generation, picocolors for terminal-colored error output, and source-map-js for source map handling. Node’s engines field (^10 || ^12 || >=14) reflects an unusually wide backward-compatibility commitment for an actively maintained library.

Code Quality 26 TypeScript test files run through the lightweight uvu test runner, with a c8 coverage configuration that enforces 100% line coverage as a hard requirement, not an aspiration. A dedicated fuzzing directory hardens the parser against malformed input, and separate integration.js/old-node.js scripts test cross-Node-version behavior. ESLint runs as its own required test step, and the shipped .d.ts type definitions are validated with check-dts rather than trusted as-authored. This is a mature, rigorously tested codebase commensurate with sitting underneath hundreds of other packages’ CI pipelines.

API Design The public surface is a single factory function, postcss(…plugins), returning a Processor whose .process(css) result supports both synchronous .css access and .then() for pipelines containing async plugins. The AST’s walk* traversal methods mirror patterns familiar from other JS-ecosystem AST tools (e.g. Babel’s visitor style), which lowers the learning curve for anyone who has written a codemod before. The main friction newcomers hit is historical: a deprecated postcss.plugin() helper (kept for backward compatibility, emits a runtime warning) and the dual CJS/ESM export surface both add a small amount of legacy surface area a brand-new API wouldn’t have.