{"id":13799,"library":"postcss-values-parser","title":"PostCSS CSS Value Parser","description":"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.","status":"active","version":"7.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/shellscape/postcss-values-parser","tags":["javascript","css","less","ast","postcss","value","values","parser","parsing"],"install":[{"cmd":"npm install postcss-values-parser","lang":"bash","label":"npm"},{"cmd":"yarn add postcss-values-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add postcss-values-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency as it leverages PostCSS's tokenizer and AST model. Required for integration into a PostCSS plugin chain.","package":"postcss","optional":false}],"imports":[{"note":"Since v7.0.0, `postcss-values-parser` is a pure ESM package. CommonJS `require()` is no longer supported.","wrong":"const { parse } = require('postcss-values-parser');","symbol":"parse","correct":"import { parse } from 'postcss-values-parser';"},{"note":"Individual node types like `Word` are exported for direct inspection or creation of AST nodes.","wrong":null,"symbol":"Word","correct":"import { Word } from 'postcss-values-parser';"},{"note":"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.","wrong":null,"symbol":"registerWalkers","correct":"import { registerWalkers } from 'postcss-values-parser';"}],"quickstart":{"code":"import { parse, registerWalkers } from 'postcss-values-parser';\n\n// Example CSS property value\nconst cssValue = 'linear-gradient(to right, #f6e32d, #f6e32d 50%, #685a21) var(--custom-spacing, 1rem)';\n\n// Parse the CSS value into an AST root node\nconst root = parse(cssValue);\n\n// Register walkers to enable methods like walkWords on the root node (v7.0.0+)\nregisterWalkers(root);\n\nconsole.log('Parsed AST root:');\nconsole.log(root.toString());\n\nconsole.log('\\nWalking nodes:');\nroot.walk((node) => {\n  console.log(`  Type: ${node.type}, Value: ${node.value || '(N/A)'}`);\n});\n\nconsole.log('\\nExtracting colors:');\nroot.walkWords((wordNode) => {\n  if (wordNode.isColor) {\n    console.log(`  Found color: ${wordNode.value}`);\n  }\n});\n\n// Demonstrating node manipulation (e.g., changing a color)\nroot.walkWords((wordNode) => {\n  if (wordNode.value === '#f6e32d') {\n    wordNode.value = '#FF0000'; // Change color to red\n  }\n});\n\nconsole.log('\\nModified AST root:');\nconsole.log(root.toString());\n","lang":"typescript","description":"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)."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Upgrade your Node.js environment to version 20.19.0 or newer. Check your `nvm` or system Node.js installation.","message":"Node.js v20.19.0 or higher is required starting from version 7.0.0, enforced by the `engines` field in `package.json`.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Call `registerWalkers(root)` after parsing the value to enable helper methods. For example: `const root = parse(value); registerWalkers(root); root.walkWords(...)`.","message":"In 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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=6.0.0 <7.0.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0 <4.0.0"}],"env_vars":null,"search_vec":"'7.0.0':56 'abstract':21 'address':131 'aim':82 'appear':117 'ast':24,86,137 'bug':132 'build':63 'built':27 'cadenc':116 'color':99 'consist':44 'conveni':88 'correct':70 'css':2,16,66,109,135 'css-tree':65 'current':52 'design':13 'develop':46 'driven':120 'ecosystem':31 'ensur':43 'esm':78 'familiar':47 'fix':133 'follow':37 'improv':69 'javascript':11,134 'less':136 'leverag':32 'librari':12,81 'mainten':129 'make':102 'manipul':108 'mark':58 'method':89 'node':39,92 'packag':79 'pars':15,97,142 'parser':4,8,141 'pattern':42 'perform':72 'plugin':50 'postcss':1,6,30,33,49,113,125,138 'postcss-values-pars':5 'power':105 'properti':17,95 'provid':84 'pure':77 'refactor':123 'releas':115,130 'rewrit':61 'robust':85 'signific':60,122 'similar':38 'specif':94 'stabl':53 'stringifi':91 'syntax':22 'token':35 'tool':106 'transit':74 'travers':41,87 'tree':23,67 'unit':98 'updat':127 'upon':28 'valu':3,7,18,110,139,140 'variabl':101 'version':54,126 'within':111 'workflow':114","created_at":"2026-04-20T01:56:22.246453+00:00","updated_at":"2026-04-20T01:56:22.246453+00:00","problems":[{"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';`.","cause":"Attempting to use `require()` to import `postcss-values-parser` in a CommonJS environment, while the package is now pure ESM since v7.0.0.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/postcss-values-parser/index.js from ... not supported."},{"fix":"After parsing, call `registerWalkers(root)` to enable these helper methods: `const root = parse(value); registerWalkers(root); root.walkWords(...)`.","cause":"In `postcss-values-parser` v7.0.0+, walker helper methods like `walkWords` are no longer attached to the root node by default.","error":"TypeError: root.walkWords is not a function"},{"fix":"Update your PostCSS dependency to meet the version required by `postcss-values-parser`. For example, `npm install postcss@^8.4.14`.","cause":"Mismatched PostCSS peer dependency. `postcss-values-parser` expects a newer version of PostCSS than what is installed or available in the project.","error":"Error: PostCSS plugin postcss-values-parser requires PostCSS 8.x.x (running 7.x.x)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/postcss-values-parser","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}