Registry / web-framework / postcss-values-parser

postcss-values-parser

library7.0.0jsnpmunverified

postcss-values-parser is a JavaScript library designed to parse CSS property values into an Abstract Syntax Tree (AST). It is built upon the PostCSS ecosystem, leveraging PostCSS's tokenizer and following similar node and traversal patterns, ensuring consistency for developers familiar with PostCSS plugins. The current stable version is 7.0.0, which marked a significant rewrite, now building on `css-tree` for improved correctness and performance, and transitioning to a pure ESM package. The library aims to provide robust AST traversal, convenience methods for stringifying nodes, and specific properties for parsing units, colors, and variables, making it a powerful tool for manipulating CSS values within a PostCSS workflow. Release cadence appears to be driven by significant refactors and PostCSS version updates, with maintenance releases addressing bug fixes.

web-framework serialization

npm install postcss-values-parser

package ↗

INSTALL

IMPORT

SIG · POSTCSS-VALUES-PAR

postcss-values-parser

web-frameworkjavascriptv7.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

parse

✓ import { parse } from 'postcss-values-parser';

✗ const { parse } = require('postcss-values-parser');

Since v7.0.0, `postcss-values-parser` is a pure ESM package. CommonJS `require()` is no longer supported.

Word

✓ import { Word } from 'postcss-values-parser';

Individual node types like `Word` are exported for direct inspection or creation of AST nodes.

registerWalkers

✓ import { registerWalkers } from 'postcss-values-parser';

Introduced in v7.0.0, `registerWalkers()` is used to explicitly enable walker helpers like `walkWords` on the root node, as they are no longer attached by default.

This quickstart demonstrates parsing a complex CSS value, traversing its AST using `walk` and `walkWords`, and performing a basic modification of a node (changing a color value).

import { parse, registerWalkers } from 'postcss-values-parser'; // Example CSS property value const cssValue = 'linear-gradient(to right, #f6e32d, #f6e32d 50%, #685a21) var(--custom-spacing, 1rem)'; // Parse the CSS value into an AST root node const root = parse(cssValue); // Register walkers to enable methods like walkWords on the root node (v7.0.0+) registerWalkers(root); console.log('Parsed AST root:'); console.log(root.toString()); console.log('\nWalking nodes:'); root.walk((node) => { console.log(` Type: ${node.type}, Value: ${node.value || '(N/A)'}`); }); console.log('\nExtracting colors:'); root.walkWords((wordNode) => { if (wordNode.isColor) { console.log(` Found color: ${wordNode.value}`); } }); // Demonstrating node manipulation (e.g., changing a color) root.walkWords((wordNode) => { if (wordNode.value === '#f6e32d') { wordNode.value = '#FF0000'; // Change color to red } }); console.log('\nModified AST root:'); console.log(root.toString());

Debug

Known issues

breakingVersion 7.0.0 of `postcss-values-parser` is a pure ESM package. It no longer provides CommonJS output, and `require('postcss-values-parser')` will fail.

fix

Migrate your project to use ES modules (`import { parse } from 'postcss-values-parser';`) or stick to an earlier version if CommonJS is a strict requirement.

affects: >=7.0.0

breakingNode.js v20.19.0 or higher is required starting from version 7.0.0, enforced by the `engines` field in `package.json`.

fix

Upgrade your Node.js environment to version 20.19.0 or newer. Check your `nvm` or system Node.js installation.

affects: >=7.0.0

breakingIn v7.0.0, walker helper methods (e.g., `walkWords`, `walkColors`) are no longer attached to the `root` node by default. You must explicitly register them.

fix

Call `registerWalkers(root)` after parsing the value to enable helper methods. For example: `const root = parse(value); registerWalkers(root); root.walkWords(...)`.

affects: >=7.0.0

breakingVersion 6.0.0 updated the peer dependency for PostCSS to a newer version (implied by `feat!: update PostCSS`). This might lead to compatibility issues if an older PostCSS version is used.

fix

Ensure your project's `postcss` dependency meets the `^8.4.14` requirement for `postcss-values-parser` v6.x, or `^8.4.14` for v7.x as well. Update PostCSS if necessary.

affects: >=6.0.0 <7.0.0

breakingVersion 3.0.0 was a complete rewrite, leveraging PostCSS's internal tokenizer and parser more extensively. This introduced many breaking changes to the internal API and node structure compared to v2.x.

fix

Review the v3.0.0 release notes and documentation carefully. Existing code written for v2.x will likely require significant refactoring to adapt to the new AST structure and API.

affects: >=3.0.0 <4.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/postcss-values-parser/index.js from ... not supported.

Attempting to use `require()` to import `postcss-values-parser` in a CommonJS environment, while the package is now pure ESM since v7.0.0.

fix

Convert your importing file to an ES module (e.g., rename `.js` to `.mjs` or add `"type": "module"` to `package.json`), and use `import { parse } from 'postcss-values-parser';`.

TypeError: root.walkWords is not a function

In `postcss-values-parser` v7.0.0+, walker helper methods like `walkWords` are no longer attached to the root node by default.

fix

After parsing, call `registerWalkers(root)` to enable these helper methods: `const root = parse(value); registerWalkers(root); root.walkWords(...)`.

Error: PostCSS plugin postcss-values-parser requires PostCSS 8.x.x (running 7.x.x)

Mismatched PostCSS peer dependency. `postcss-values-parser` expects a newer version of PostCSS than what is installed or available in the project.

fix

Update your PostCSS dependency to meet the version required by `postcss-values-parser`. For example, `npm install postcss@^8.4.14`.

Upgrade

Version history

7.0.0latest on npm

Audit

Dependencies

postcssrequiredPeer dependency as it leverages PostCSS's tokenizer and AST model. Required for integration into a PostCSS plugin chain.

Agent activity

6 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/postcss-values-parser ↗