css-parser
A zero-allocation, high-performance CSS processing engine for Node.js and the browser, combining parsing, validation, transformation, minification, and AST-based tooling in a single solution.
Every stylesheet is fully parsed into a structured AST, with token values represented as typed data. This provides a reliable semantic foundation for custom transformations, plugin development, and advanced stylesheet analysis without relying on raw string manipulation.
[!NOTE]
Version 2.2.0 has been rewritten to use arena memory for AST nodes and tokens, improving memory usage and performance. On the Tailwind CSS parsing and validation workload, runtime is 59% faster than v1.8.2 while using less memory.
This major release also introduces breaking changes and removes deprecated features. See the migration guide for details.
Installation
From npm
$ npm install @tbela99/css-parser
from jsr
$ deno add @tbela99/css-parser
Features
- Zero dependencies — lightweight and easy to integrate into any project.
- All-in-one CSS parsing solution covering parsing, validation, transformation, minification, and AST manipulation.
- Standards-based CSS validation powered by the W3C specification definitions (@webref/css).
- Full CSS Modules support for modern component-based workflows.
- Fault-tolerant parsing that follows the CSS Syntax Module Level 3 specification and always produces a complete, structured parse result.
- Typed tokens and AST — parsed CSS is exposed as strongly typed tokens and nodes so plugins and transforms can operate on semantic structures.
- High-performance minification with safe optimizations and no unsafe transforms.
- Advanced color processing with support for modern color spaces and functions, including
color(), lab(), lch(), oklab(), oklch(), color-mix(), light-dark(), system colors, and relative colors.
- Color conversion engine capable of transforming colors between all supported formats.
- Automatic CSS nesting generation from compatible selectors.
- Source map generation for easier debugging and development workflows.
- Shorthand property computation to reduce output size and improve optimization.
- Transform function optimization for more compact CSS output.
- Math function evaluation, including
calc(), clamp(), min(), max(), and related expressions.
- CSS variable inlining where values can be safely resolved.
- Duplicate declaration removal to eliminate redundant rules.
@import flattening to produce self-contained stylesheets.
- Vendor prefix cleanup to modernize generated CSS.
- Binary input — the css can be a string, an
ArrayBuffer or an ArrayBufferView (utf-8 bytes, Uint8Array, Buffer): an ASCII buffer is tokenized without copy.
- Experimental: evaluate @mixin and @function
- 51.5kb once minified and gzipped.
Vendor prefix removal
Vendor prefix cleanup to modernize generated CSS.
Syntax lowering
CSS-Parser can transform these modern CSS features into lower-level CSS syntax:
- Nested CSS transpilation to legacy-compatible syntax.
if() function transpilation for broader browser compatibility.
- CSS mixins and custom functions evaluation the
@apply rules are replaced by the mixin body, the custom function calls are replaced by their result.
color-mix() function conversion convert new color-mix() syntax to any of the supported colors.
Benchmark
Across all tested datasets, css-parser consistently produces the smallest output among the benchmarked tools, including Lightning CSS, cssnano, csso, clean-css, css-tree, and esbuild.
The benchmark evaluates minification effectiveness on a diverse set of real-world stylesheets, including Bootstrap 4, Bootstrap 5, Tailwind CSS, Animate.css, Foundation, Font Awesome, Normalize.css, and others.
A sample result:
| File |
ligthningcss |
CSS Parser |
| tailwind.css - 2380419 bytes |
1864728 bytes |
1624148 bytes |
| bootstrap-4.css - 200078 bytes |
153616 bytes |
144391 bytes |
| bootstrap-5.css - 205481 bytes |
159987 bytes |
150764 bytes |
On the complete benchmark suite, css-parser generated a total output size of 2,158,698 bytes, compared to 2,494,113 bytes for Lightning CSS and larger outputs for all other tested minifiers.
While some tools prioritize raw execution speed, css-parser focuses on maximizing compression while preserving stylesheet semantics, resulting in consistently smaller production bundles.
Minification performance vs execution speed
css-parser is designed for maximum minification performance, but the optimal configuration depends on what matters most for your workload.
The parser provides settings that let you choose the balance between minification performance and execution speed:
Minification performance: prioritize the quality and efficiency of the minification process, allowing the parser to perform additional work when generating the minimized output.
Execution speed: minimize the amount of work performed during parsing and minification to achieve the fastest possible execution time.
However, the available settings allow you to shift the balance toward execution speed when minimizing runtime is more important than performing every available minification optimization.
The example below demonstrates a balanced configuration that improves execution speed by disabling advanced minification features.
import {transformSync} from "@tbela99/css-parser";
const css = `...`;
const result = transformSync({
input: css,
minify: false,
beautify: false,
removeEmpty: true,
removeComments: true,
convertColor: true,
minifyValues: true,
});
console.debug(result.code);
console.debug(result.stats);
Performance vs execution speed comparison
| File: tailwind.css |
Speed optimization |
Minification optimization |
| Size: 2,380,419 bytes |
1,890,835 bytes |
1,633,188 bytes |
| Time |
109.07 ms |
191.85 ms |
| Size reduction |
-20.7% |
-31.8% |
Playground
Try it online
Documentation
AST
Ast nodes and value tokens are allocated in an arena (AstArena) and referenced by their id (a number). The node data is stored
column-wise in typed arrays (structure of arrays) and is read / written through the arena. The parser does not allocate
node or token objects:
import {parse, render, EnumToken} from '@tbela99/css-parser';
const {arena, ast} = await parse(`.foo { color: red }`);
const rule = arena.getFirstChild(ast);
const declaration = arena.getFirstChild(rule);
console.log(arena.getType(rule) == EnumToken.RuleNodeType, arena.getSelector(rule)); // true '.foo'
console.log(arena.getName(declaration)); // 'color'
console.log(arena.tokens(declaration).map((token) => [EnumToken[arena.getType(token)], arena.str(token)])); // [['Color', 'red']]
console.log(render(arena, ast).code); // .foo{color:red}
Comment
arena.getType(n): EnumToken.CommentNodeType
arena.getValue(n): string, the comment
StyleSheet
arena.getType(n): EnumToken.StyleSheetNodeType
arena.children(n): array of children ids
Declaration
arena.getType(n): EnumToken.DeclarationNodeType
arena.getName(n): string, declaration name
arena.tokens(n): array of token ids, the declaration value
arena.getState(n): EnumAstNodeStatus, validation state
arena.getErrors(n): ErrorDescription[], validation errors
Rule and KeyframesRule
arena.getType(n): EnumToken.RuleNodeType or EnumToken.KeyframesRuleNodeType
arena.getSelector(n): string, css selector
arena.tokens(n): array of token ids, the parsed selector
arena.children(n): array of children ids
arena.getState(n): EnumAstNodeStatus, validation state
arena.getErrors(n): ErrorDescription[], validation errors
AtRule and KeyframesAtRule
arena.getType(n): EnumToken.AtRuleNodeType or EnumToken.KeyframesAtRuleNodeType
arena.getName(n): string. AtRule name
arena.getValue(n): rule prelude
arena.tokens(n): array of token ids, the parsed prelude
arena.children(n): array of children ids (at-rules with a block)
arena.getState(n): EnumAstNodeStatus, validation state
arena.getErrors(n): ErrorDescription[], validation errors
Object views
arena.toObject(id) returns an object view of a node or a token (AstArenaNode): its properties (typ, nam, sel,
val, chi, tokens, loc, state, errors, parent, ...) are getters and setters that read and write the arena.
The view only holds the arena and the node id (view[ARENAID]). Importing a view of the same arena is a noop:
const rule = arena.toObject(arena.getFirstChild(ast));
rule.sel = '.bar';
rule.chi[0].nam = 'background-color';
// the returned arrays are frozen: assign the property to modify the arena
rule.chi = [...rule.chi, {typ: EnumToken.DeclarationNodeType, nam: 'width', val: [{typ: EnumToken.LengthTokenType, val: 3, unit: 'px'}]}];
console.log(arena.fromObject(rule) == rule[ARENAID]); // true: nothing is copied
console.log(JSON.stringify(rule)); // deep plain copy
Traversal and visitors
The traversal and search functions are methods of the arena: arena.walk(), arena.walkValues(), arena.find(),
arena.findAll(), arena.findLast(), arena.findByValue(), arena.findValue(). They return node ids. Their callbacks,
like the visitors, are called with the arena and the node id: everything else is read from the arena.
for (const node of arena.walk(ast)) {
console.log(EnumToken[arena.getType(node)], arena.getParent(node));
}
const result = await transform(css, {
visitor: {
Declaration(arena: AstArena, id: number) {
const node = arena.toObject(id);
if (node.nam == 'height') {
node.nam = 'width';
}
}
}
});
A visitor returns nothing to keep the node, or an object or a node id (or an array of objects and node ids) to replace it.
Arena memory
The arena never frees memory by itself: detached nodes keep their memory and their ids stay valid. A long-lived arena
can be compacted. compact() and trim() renumber the nodes and return the mapping of the old ids to the new ids:
console.log(arena.getCapacity(), arena.getLastId(), arena.getStringCount()); // capacity, last allocated id, interned strings
arena.mark(node); // mark a node to be released later
const mapping = arena.trim(result.errors); // release the marked nodes, drop the unreachable nodes, shrink the columns
const newId = mapping[oldId]; // 0 when the node has been dropped
See Arena Memory.
Workers
The arena can be moved to a worker (and back) without copying the node data:
// main thread
const [properties, transferables] = AstArena.toTransferableArenaObject(result.arena);
worker.postMessage({ast: result.ast, properties, transferables}, transferables);
// worker
const arena = AstArena.fromTransferableArenaObjects(event.data.properties, event.data.transferables);
console.log(render(arena, event.data.ast).code);
See Ast Manipulation.
Sourcemap
- Sourcemap generation
- Input sourcemap: when the input CSS comes from another tool, you can pass the sourcemap content to link the generated CSS positions to the original files.
Computed shorthands properties
-
all
- animation
- background
- border
- border-block-end
- border-block-start
- border-bottom
- border-color
- border-image
- border-inline-end
- border-inline-start
- border-left
- border-radius
- border-right
- border-style
- border-top
- border-width
- column-rule
- columns
- container
- contain-intrinsic-size
- flex
- flex-flow
- font
- font-synthesis
- font-variant
- gap
- grid
- grid-area
- grid-column
- grid-row
- grid-template
- inset
- list-style
- margin
- margin-block
- margin-inline
- mask
- offset
- outline
- overflow
- padding
- padding-block
- padding-inline
- place-content
- place-items
- place-self
- scroll-margin
- scroll-padding
- scroll-timeline
- text-decoration
- text-emphasis
- transition
Performance
- Bundle file referenced by the @import statement.
Architecture
