CSS Simple Parser is a highly optimized, lightweight parser for (S)CSS strings, weighing in at approximately 1.5kb (min + gzip). It is designed for blazing-fast performance, benchmarking around 100x faster than PostCSS for typical use cases. Currently at version 3.0.2, the library is actively maintained but adheres to a 'too simple' philosophy, focusing on core rule block parsing. Key differentiators include its small footprint and speed, achieved by intentionally limiting its scope. It supports nested (S)CSS rules but does not handle top-level directives like `@charset` or `@import`, nor does it permit curly braces (`{`, `}`) or semicolons (`;`) within string literals. The Abstract Syntax Tree (AST) it generates is intentionally crude, requiring further processing for complex operations. Its release cadence is feature-driven, with new versions addressing enhancements or bug fixes within its defined scope.
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.
The library exports a default object named `Parser`, which encapsulates all utility methods like `parse`, `stringify`, and `traverse`.
import Parser from 'css-simple-parser';
The `parse` function is a method of the default `Parser` object, not a direct named export. Access it via `Parser.parse()`.
import Parser from 'css-simple-parser'; const ast = Parser.parse('.foo {}');
While CommonJS `require` is supported, ES module `import` syntax is generally preferred for modern TypeScript and JavaScript projects, especially when consuming libraries with type definitions.
const Parser = require('css-simple-parser');
Demonstrates parsing a CSS string with nested rules, traversing the resulting AST to extract selectors, stringifying the AST back into CSS, and then performing a simple AST modification followed by re-stringification.
import Parser from 'css-simple-parser';
const cssString = `
.container {
display: flex;
.item {
color: red;
&:hover {
color: blue;
}
}
}
@media screen and (max-width: 768px) {
.container {
flex-direction: column;
}
}
`;
console.log("Parsing CSS string...");
const ast = Parser.parse(cssString);
console.log("Generated AST (truncated):\n", JSON.stringify(ast, null, 2).substring(0, 300) + '...\n');
console.log("Traversing AST and logging selectors:");
let selectorsFound: string[] = [];
Parser.traverse(ast, node => {
selectorsFound.push(node.selector);
});
console.log(selectorsFound.join(', ') + '\n');
console.log("Stringifying AST back to CSS (truncated to 150 chars):");
const stringifiedCss = Parser.stringify(ast);
console.log(stringifiedCss.substring(0, 150) + '...\n');
// Example of modifying the AST and stringifying again
if (ast.children.length > 0 && ast.children[0].children.length > 0) {
const firstNestedItem = ast.children[0].children[0];
console.log(`Modifying selector '${firstNestedItem.selector}' to '.new-item-class'\n`);
firstNestedItem.selector = '.new-item-class';
const modifiedStringifiedCss = Parser.stringify(ast);
console.log("Modified CSS (truncated to 150 chars):\n", modifiedStringifiedCss.substring(0, 150) + '...');
}
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.