css-parser

CSS parser, transformer, minifier and validator for node and the browser

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.
• Standards-based CSS validation powered by MDN data.
• Full CSS Modules support for modern component-based workflows.
• Fault-tolerant parsing that follows the CSS Syntax Module Level 3 specification.
• 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 removal

Experimental 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.
• 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	1633251 bytes
bootstrap-4.css - 200078 bytes	153616 bytes	144700 bytes
bootstrap-5.css - 205481 bytes	159987 bytes	151258 bytes

On the complete benchmark suite, css-parser generated a total output size of 2,204,888 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.

Playground

Try it online

Documentation

• Installation
• Usage
  • Parsing CSS
  • Parsing files
  • Parsing streams
  • Rendering AST
  • Transform
• Validation
• CSS Modules
• Minification
• Custom Transform
• Ast Manipulation
• Utility Functions

AST

Comment

• typ: number
• val: string, the comment

Declaration

• typ: number
• nam: string, declaration name
• val: array of tokens
• state: EnumAstNodeStatus, validation state
• errors: ErrorDescription[], validation errors

Rule

• typ: number
• sel: string, css selector
• chi: array of children
• state: EnumAstNodeStatus, validation state
• errors: ErrorDescription[], validation errors

AtRule

• typ: number
• nam: string. AtRule name
• val: rule prelude
• state: EnumAstNodeStatus, validation state
• errors: ErrorDescription[], validation errors

AtRuleStyleSheet

• typ: number
• chi: array of children

KeyFrameRule

• typ: number
• sel: string, css selector
• chi: array of children
• state: EnumAstNodeStatus, validation state
• errors: ErrorDescription[], validation errors

Sourcemap

• Sourcemap generation

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
• mask
• offset
• outline
• overflow
• padding
• 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.