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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
gonzales
✓ const gonzales = require('gonzales-pe');
✗ import gonzales from 'gonzales-pe';
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.
parse
✓ const parseTree = gonzales.parse(cssString, { syntax: 'scss' });
✗ import { parse } from 'gonzales-pe';
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.
createNode
✓ const newNode = gonzales.createNode({ type: 'ident', content: 'value' });
✗ import { createNode } from 'gonzales-pe';
Similar to 'parse', 'createNode' is a method of the main 'gonzales' export.
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.
const gonzales = require('gonzales-pe');
// Example 1: Parsing CSS/SCSS and converting back to string
const cssInput = `
a {
color: tomato;
font-size: 16px;
}
.button {
display: flex;
justify-content: center;
align-items: center;
&_primary {
background-color: blue;
}
}
`;
console.log('--- Original CSS ---\n' + cssInput);
// Parse the SCSS (default syntax is 'css', explicitly set for SCSS features)
const parseTree = gonzales.parse(cssInput, { syntax: 'scss' });
// Example 2: Modifying the tree - Find a property and change its value
parseTree.walk(node => {
if (node.type === 'declaration' && node.content[0].content === 'color') {
node.content[2].content = 'blue'; // Modify 'tomato' to 'blue'
}
});
// Example 3: Adding a new node (e.g., a padding declaration to the 'a' rule)
const newProperty = gonzales.createNode({
type: 'declaration',
content: [
gonzales.createNode({ type: 'ident', content: 'padding' }),
gonzales.createNode({ type: 'operator', content: ':' }),
gonzales.createNode({ type: 'dimension', content: ['10', 'px'] })
]
});
// Find the rule for 'a' (assuming it's the first one) and add the new property
parseTree.content[0].content[3].content.push(newProperty);
// Convert the modified tree back to a string
const modifiedCss = parseTree.toString();
console.log('\n--- Modified CSS ---\n' + modifiedCss);
// Example 4: Checking for a node type or content
const hasFlex = parseTree.contains('ident', 'flex');
console.log(`\nDoes the CSS contain 'flex'? ${hasFlex ? 'Yes' : 'No'}`);
Debug
Known issues
gotchaThe 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.fixWhile 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.
affects: All versions when installed from 'dev' branch
gotchaThe `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.fixTest thoroughly on your target Node.js version. If issues arise, check for specific Node.js API deprecations or polyfills.
affects: <4.3.0
breakingVersion 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.fixReview any existing code that traverses or modifies the AST, particularly around selectors or properties containing asterisks, to ensure compatibility with the corrected parsing behavior.
affects: >=3.4.6
gotchaPrior 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.fixUpgrade 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.
affects: <4.2.4
Errors
Common errors & fixes
Error: Cannot find module 'gonzales-pe'
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.
fixEnsure `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.
TypeError: gonzales.parse is not a function
`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).
fixVerify 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';`. Parsing error: Expected IDENT, got OPERATOR
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).
fixCorrect the syntax error in your input CSS string, or ensure `gonzales.parse(css, { syntax: 'scss' })` (or `less`, `sass`) matches the input language being parsed. Audit
Dependencies
No dependency data recorded yet.