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

• [x] Sourcemap generation

Computed shorthands properties

• [ ] ~all~
• [x] animation
• [x] background
• [x] border
• [ ] border-block-end
• [ ] border-block-start
• [x] border-bottom
• [x] border-color
• [ ] border-image
• [ ] border-inline-end
• [ ] border-inline-start
• [x] border-left
• [x] border-radius
• [x] border-right
• [x] border-style
• [x] border-top
• [x] border-width
• [x] column-rule
• [x] columns
• [x] container
• [ ] contain-intrinsic-size
• [x] flex
• [x] flex-flow
• [x] font
• [ ] font-synthesis
• [ ] font-variant
• [x] gap
• [ ] grid
• [ ] grid-area
• [ ] grid-column
• [ ] grid-row
• [ ] grid-template
• [x] inset
• [x] list-style
• [x] margin
• [ ] mask
• [ ] offset
• [x] outline
• [x] overflow
• [x] padding
• [ ] place-content
• [ ] place-items
• [ ] place-self
• [ ] scroll-margin
• [ ] scroll-padding
• [ ] scroll-timeline
• [x] text-decoration
• [x] text-emphasis
• [x] transition

Performance

• [x] Bundle file referenced by the @import statement.