postcss-value-parser

postcss-value-parser turns a CSS declaration value or at-rule parameter string into a structured tree of nodes — words, functions, dividers, spaces, and strings — and provides a small traversal and serialization API for working with it. Instead of matching CSS values with brittle regular expressions, tools can parse a value once and walk or rewrite specific pieces.

It is a foundational utility in the PostCSS ecosystem, used by countless plugins to inspect and transform values like url(foo.png) no-repeat 40px 73% or rgba(233, 45, 66, .5). The parser is lossless — toString() reconstructs the exact original input including whitespace — and has no runtime dependencies, which is why it sees tens of millions of weekly downloads.

What You Get

• A parser that converts any CSS value or at-rule parameter into a tree of typed nodes
• A walk() traversal API for visiting and mutating nodes, including nested function arguments
• Lossless toString()/stringify that reconstructs the original value exactly, including whitespace
• Node types for words, functions, strings, dividers, and spaces, plus a unit() helper for numeric values

Common Use Cases

• Building PostCSS plugins that transform specific parts of CSS values
• Rewriting url() references or function arguments during a build
• Extracting and analyzing numeric values, units, or color functions from CSS

Under The Hood

Architecture — The library is split into focused modules under lib/: parse.js tokenizes a value string into typed nodes, walk.js implements depth-first traversal with the ability to skip subtrees, stringify.js reconstructs CSS from a node tree, and unit.js splits a numeric token into number and unit. index.js composes these into the callable valueParser factory, with types in index.d.ts.

Tech Stack — Plain JavaScript with zero runtime dependencies, distributed as CommonJS with bundled TypeScript declarations. It is developed under the PostCSS organization.

Code Quality — The test/ directory contains dedicated suites for parsing, stringifying, unit handling, and the top-level API (parse.js, stringify.js, unit.js, index.js), covering the round-trip and edge cases that matter for a value parser.

API Design — The public surface is deliberately minimal: call valueParser(value) to get a tree, then .walk() to traverse and .toString() to serialize. Node objects preserve before/after whitespace so transformations stay lossless, and the API composes cleanly inside PostCSS plugins.