Registry / serialization / css-simple-parser

css-simple-parser

library3.0.2jsnpmunverified

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.

serialization

npm install css-simple-parser

github ↗package ↗

INSTALL

IMPORT

SIG · CSS-SIMPLE-PARSER

css-simple-parser

serializationjavascriptv3.0.2

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.

Parser

✓ import Parser from 'css-simple-parser';

✗ import { Parser } from 'css-simple-parser';

The library exports a default object named `Parser`, which encapsulates all utility methods like `parse`, `stringify`, and `traverse`.

parse

✓ import Parser from 'css-simple-parser'; const ast = Parser.parse('.foo {}');

✗ import { parse } 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()`.

Parser (CommonJS)

✓ const Parser = require('css-simple-parser');

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.

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) + '...'); }

Debug

Known issues

gotchaThis parser is not a full-blown CSS parser and has significant limitations. It only supports rule blocks at the top-level, meaning directives like `@charset`, `@import`, or top-level `@media` rules are not parsed.

fix

Ensure your CSS input strictly adheres to the supported syntax (primarily nested rule blocks). For full CSS specification compliance and advanced features, consider using a more comprehensive parser like PostCSS.

affects: >=1.0.0

gotchaCurly braces (`{`, `}`) or semicolons (`;`) cannot be used inside string literals within CSS rules. For example, `div[attr="{}"]` or `content: ";"` will cause parsing errors.

fix

Refactor your CSS to avoid these characters within string literals. If your use case absolutely requires them, this parser is not suitable, and an alternative like `css-tree` should be considered.

affects: >=1.0.0

gotchaThe Abstract Syntax Tree (AST) generated by `css-simple-parser` is deliberately crude and simplified. It provides basic structural information but lacks the rich detail and metadata found in ASTs from more complex parsers.

fix

Be prepared to implement custom logic to process the simplified AST nodes to extract specific information or perform advanced manipulations. If you need a highly detailed or standardized AST, explore libraries like `css-tree` or `PostCSS`.

affects: >=1.0.0

Errors

Common errors & fixes

Syntax Error: Unexpected character '{' (or '}') in string

A curly brace (`{` or `}`) was found inside a CSS string literal, which is explicitly disallowed by this parser.

fix

Modify your CSS to remove `{` or `}` characters from within string values (e.g., `content: "{}"` is invalid). If these characters are essential, `css-simple-parser` cannot be used.

Syntax Error: Unexpected character ';' in string

A semicolon (`;`) was found inside a CSS string literal, which is explicitly disallowed.

fix

Modify your CSS to remove `;` characters from within string values (e.g., `div[attr=";foo"]` is invalid). If necessary, switch to a more robust parser.

Parsing failed: Expected rule block at top level

The input CSS contains a top-level construct other than a rule block, such as `@import`, `@charset`, or `@media`, which are not supported at the root level by `css-simple-parser`.

fix

Ensure your CSS only contains standard rule blocks (e.g., `.selector { ... }`) or nested rules. If you need to parse full CSS specifications, use a different parsing library.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/fabiospampinato/css-simple-parser ↗

packagehttps://www.npmjs.com/package/css-simple-parser ↗