{"id":13244,"library":"gonzales-pe","title":"Gonzales PE","description":"Gonzales PE is a high-performance CSS parser library for JavaScript, designed to parse CSS, SCSS, Sass, and LESS syntaxes into a detailed Abstract Syntax Tree (AST). It provides a programmatic API for traversing, modifying, and regenerating CSS structures. The current stable version is 4.3.0. While the exact release cadence is not explicitly stated, the project has seen consistent updates, with several patch and minor releases within the v3 and v4 series, indicating active maintenance. Key differentiators include its explicit support for popular CSS preprocessors, making it suitable for tools that need to understand and manipulate these syntaxes, and its focus on providing a low-level AST for granular control over the stylesheet structure. The library allows users to parse a string, create and modify nodes, and then convert the tree back into a CSS string.","status":"active","version":"4.3.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/tonyganch/gonzales-pe","tags":["javascript"],"install":[{"cmd":"npm install gonzales-pe","lang":"bash","label":"npm"},{"cmd":"yarn add gonzales-pe","lang":"bash","label":"yarn"},{"cmd":"pnpm add gonzales-pe","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Gonzales PE is primarily a CommonJS module. Direct ES Module 'import' syntax may not work without a build step or specific Node.js configuration, and is not officially supported in examples.","wrong":"import gonzales from 'gonzales-pe';","symbol":"gonzales","correct":"const gonzales = require('gonzales-pe');"},{"note":"The 'parse' function is a method of the default 'gonzales' export. Do not attempt to destructure it from the module root unless specifically bundled for ESM with named exports.","wrong":"import { parse } from 'gonzales-pe';","symbol":"parse","correct":"const parseTree = gonzales.parse(cssString, { syntax: 'scss' });"},{"note":"Similar to 'parse', 'createNode' is a method of the main 'gonzales' export.","wrong":"import { createNode } from 'gonzales-pe';","symbol":"createNode","correct":"const newNode = gonzales.createNode({ type: 'ident', content: 'value' });"}],"quickstart":{"code":"const gonzales = require('gonzales-pe');\n\n// Example 1: Parsing CSS/SCSS and converting back to string\nconst cssInput = `\na {\n  color: tomato;\n  font-size: 16px;\n}\n.button {\n  display: flex;\n  justify-content: center;\n  align-items: center;\n  &_primary {\n    background-color: blue;\n  }\n}\n`;\n\nconsole.log('--- Original CSS ---\\n' + cssInput);\n\n// Parse the SCSS (default syntax is 'css', explicitly set for SCSS features)\nconst parseTree = gonzales.parse(cssInput, { syntax: 'scss' });\n\n// Example 2: Modifying the tree - Find a property and change its value\nparseTree.walk(node => {\n  if (node.type === 'declaration' && node.content[0].content === 'color') {\n    node.content[2].content = 'blue'; // Modify 'tomato' to 'blue'\n  }\n});\n\n// Example 3: Adding a new node (e.g., a padding declaration to the 'a' rule)\nconst newProperty = gonzales.createNode({\n  type: 'declaration',\n  content: [\n    gonzales.createNode({ type: 'ident', content: 'padding' }),\n    gonzales.createNode({ type: 'operator', content: ':' }),\n    gonzales.createNode({ type: 'dimension', content: ['10', 'px'] })\n  ]\n});\n// Find the rule for 'a' (assuming it's the first one) and add the new property\nparseTree.content[0].content[3].content.push(newProperty);\n\n// Convert the modified tree back to a string\nconst modifiedCss = parseTree.toString();\n\nconsole.log('\\n--- Modified CSS ---\\n' + modifiedCss);\n\n// Example 4: Checking for a node type or content\nconst hasFlex = parseTree.contains('ident', 'flex');\nconsole.log(`\\nDoes the CSS contain 'flex'? ${hasFlex ? 'Yes' : 'No'}`);","lang":"javascript","description":"This quickstart demonstrates parsing SCSS input, traversing and modifying the AST to change a color and add a new property, then converting the modified tree back to a CSS string. It also shows how to check for specific node content."},"warnings":[{"fix":"While the project encourages `dev` branch usage, for production environments, consider vendoring a specific commit or relying on a published npm version if one exists and meets requirements for stability.","message":"The official installation instructions in the README recommend installing directly from the 'dev' branch on GitHub (`npm install --save git://...#dev`) rather than a stable npm release. This practice can lead to instability and unexpected breaking changes not adhering to semantic versioning.","severity":"gotcha","affected_versions":"All versions when installed from 'dev' branch"},{"fix":"Test thoroughly on your target Node.js version. If issues arise, check for specific Node.js API deprecations or polyfills.","message":"The `engines` field in `package.json` specifies `\"node\": \">=0.6.0\"`, indicating compatibility with extremely old Node.js versions. While it might run on modern Node.js, there could be compatibility issues or reliance on deprecated Node.js APIs, especially with internal file I/O or system-level operations, that may not function correctly or optimally on current Node.js runtimes.","severity":"gotcha","affected_versions":"<4.3.0"},{"fix":"Review any existing code that traverses or modifies the AST, particularly around selectors or properties containing asterisks, to ensure compatibility with the corrected parsing behavior.","message":"Version 3.4.6 changed the parsing logic for 'ident' nodes, which specifically fixed an issue where asterisks were incorrectly parsed as identifiers instead of operators. While a bug fix, this alters the AST structure for input that previously relied on the incorrect asterisk parsing.","severity":"breaking","affected_versions":">=3.4.6"},{"fix":"Upgrade to version 4.2.4 or higher to resolve the `node.contains()` bug. If upgrading is not immediately possible, exercise caution and thoroughly test any logic relying on this method.","message":"Prior to version 4.2.4, the `node.contains()` method had a bug with its `content` guard. This could lead to incorrect results or unexpected behavior when checking for child nodes of a given type or content.","severity":"gotcha","affected_versions":"<4.2.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `npm install gonzales-pe` (or the specific git URL with `--build-from-source`) is run. If using a git dependency, you might need to manually run `npm run init` (or `npm install` then `npm run build`) in the package's directory after cloning to generate the `lib` files.","cause":"The package was either not installed, or when installed directly from GitHub (`#dev`), the required build step for the `main` field (`./lib/gonzales`) was not executed.","error":"Error: Cannot find module 'gonzales-pe'"},{"fix":"Verify that `const gonzales = require('gonzales-pe');` is correctly executed. If using ES Modules, ensure your bundler/runtime is correctly transpiling CommonJS or use `import * as gonzales from 'gonzales-pe';`.","cause":"`gonzales` variable does not correctly reference the parser module, often due to incorrect CommonJS `require` or ES Module `import` (e.g., trying to destructure `parse` directly from a CJS module).","error":"TypeError: gonzales.parse is not a function"},{"fix":"Correct the syntax error in your input CSS string, or ensure `gonzales.parse(css, { syntax: 'scss' })` (or `less`, `sass`) matches the input language being parsed.","cause":"The input CSS/preprocessor syntax contains an error, or the `syntax` option provided to `gonzales.parse` does not match the actual language of the input (e.g., parsing SCSS as plain CSS).","error":"Parsing error: Expected IDENT, got OPERATOR"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}