A high-performance, zero-dependency, spec-compliant CSS Object Model (CSSOM) parser and query engine in pure TypeScript. Purpose-built for static analysis, testing, and eating style rules for breakfast.
Built with coding agents against 23,000+ W3C Web Platform Tests (WPT) across CSSOM, Syntax, Selectors, Cascade, Variables, Nesting, Media Queries, and Typed OM. Coding agents + conformance suites is a really fun meta-project (I recommend it!).
Why cssomnom?
Other tools like PostCSS and CSSTree expose custom Abstract Syntax Trees (ASTs) that require learning tool-specific APIs to navigate.
cssomnom implements the standard W3C CSS Object Model (CSSOM) API. You get a familiar, standardized interface to query styles directly in Node.js. For example, you can use stylesheet.cssRules[0].style.getPropertyValue('color') instead of writing complex AST traversal code.
It is uniquely suited for static analysis and automated grading where you need to evaluate CSS rules against DOM structures without the overhead of a full browser environment.
Features
Full Spec Compliance: Implements CSS Syntax Module Level 3, CSSOM Level 1, CSS Nesting, CSS Logical Properties, and Houdini specifications (Properties and Values API, Typed OM Level 1 & 2).
Cascade Resolution: Query which styles apply to a mock element without a real DOM using getCascadedStyle.
Houdini Powered: Full support for CSS.registerProperty(), CSSNumericValue.parse(), and complex math functions (e.g., calc, sin, atan2).
Fast and Buildless-Ready: Executes directly in Node.js 24.11.0+ without a build step for development, or can be consumed as a pre-bundled ESM package.
API Documentation & Quickstarts
Subpath Exports & Import Options
cssomnom provides focused subpath entrypoints depending on what you need:
// 1. Full Package ("cssomnom"): Browser CSSOM, Typed OM, W3C CSS namespace, Cascade & Node AST toolsimport { parse, getCascadedStyle, CSSNumericValue, CSS } from 'cssomnom';// 2. Lightweight Parser & CSSOM Subset ("cssomnom/parse" — ~338 KB, >60% smaller bundle!)// Minimal subset of "cssomnom" excluding Cascade, UA Stylesheet, and Typed OM; ideal for DOM shims (LinkeDOM) and workersimport { parse, CSSStyleSheet, CSSStyleDeclaration } from 'cssomnom/parse';// 3. WICG CSS Parser API Draft ("cssomnom/parser-api")import { parseStylesheet, parseRule, CSSParserAtRule, CSSParserQualifiedRule } from 'cssomnom/parser-api';
Basic CSS Parsing & Rule Traversal
Parse CSS into a standard CSSStyleSheet and traverse rules like CSSStyleRule, CSSMediaRule, and CSSNestedDeclarations.
import { parse, type CSSStyleRule, type CSSMediaRule } from 'cssomnom';const css = ` body { color: red; } @media (max-width: 600px) { body { color: blue; margin: 0; } }`;const stylesheet = parse(css);// Access a basic style ruleconst bodyRule = stylesheet.cssRules[0] as CSSStyleRule;console.log(bodyRule.style.getPropertyValue('color')); // 'red'// Access nested rules (like inside an @media block)const mediaRule = stylesheet.cssRules[1] as CSSMediaRule;const nestedBodyRule = mediaRule.cssRules[0] as CSSStyleRule;console.log(nestedBodyRule.style.getPropertyValue('margin')); // '0'
Use getRules, closestRule, resolveSelector, parseSelectorAST, getDeclaredProperties, and getPropertyValues to inspect stylesheets using standard CSSOM instances without custom wrapper objects or hand-rolled recursive visitors:
Compute the cascaded style for a particular element. You can pair cssomnom with lightweight DOM implementations like linkedom to resolve styles against HTML.
serialize(nodes: ComponentValue[] | Token[]): string — Serializes component values or tokens back to CSS text.
new StreamingTokenizer() — Class for processing chunked CSS streams.
getRules(root, RuleClass?) — Recursively collects rules in depth-first pre-order across a CSSStyleSheet, CSSRule, or Iterable<CSSRule>, optionally narrowed to instances of RuleClass (e.g. getRules(sheet, CSSStyleRule)).
closestRule(rule, ...RuleClasses) — Walks strict ancestors via rule.parentRule and returns the nearest enclosing rule matching any of RuleClasses (e.g. closestRule(rule, CSSMediaRule)).
resolveSelector(rule) — Resolves CSS Nesting & combinators and relative selectors across enclosing CSSStyleRule and @scope ancestors into a canonical selector string.
parseSelectorAST(input, options?) — Parses a selector string or CSSRule into a Selectors Level 4 SelectorList AST (resolving nested & selectors by default when given a CSSRule).
getDeclaredProperties(root, options?) — Collects all declared CSS property names across the rule tree, including parent shorthands and @supports feature queries.
getPropertyValues(target, property, options?) — Returns all authored values for property in declaration order on a CSSRule or CSSStyleDeclaration, resolving logical↔physical property aliases, unexpanded var() shorthands, and same-rule progressive-enhancement fallbacks.
getCascadedStyle(element, rulesOrSheet?, pseudoOrEnv?, envOptions?) — Computes cascaded styles against a DOM/linkedom element (accepting a CSSStyleSheet or rule list, plus optional Partial<MediaEnvironment> overrides).
resolveVariables(style: CSSStyleDeclaration, property: string, envMap?) — Resolves var() and env() substitutions on a CSSStyleDeclaration.
Architecture & Spec Boundaries
This section outlines the boundaries between standard CSSOM specifications (src/entry/spec.ts) and standalone Node tooling (src/entry/tools.ts).
1. Standard CSSOM Layer (src/entry/spec.ts)
These APIs are defined in the CSSOM-1 specification and related module extensions (CSS Conditional Rules, CSS Nesting, CSS Anchor Positioning, CSS Fonts, CSS Animations, CSS Paged Media, CSS View Transitions, and CSS Cascade). They are designed to mirror standard browser CSSOM APIs in Node.js and headless environments, and are verified bidirectionally against W3C WebIDL definitions via webidl2.js in tests/api-surface.test.ts.
Rule Constructors: Standard CSSOM rules are typically instantiated via insertRule() or stylesheet parsing. CSSStyleSheet supports standard CSSStyleSheetInit options (new CSSStyleSheet({ baseURL, media, disabled })).
Synchronous CSSStyleSheet.prototype.replace(): While the CSSOM-1 specification specifies parallel parsing for replace(), our implementation executes parsing synchronously via replaceSync() and returns Promise.resolve(this).
CSSImportRule.styleSheet: Evaluates to null because the library operates as a static, offline parser without network or disk I/O to load external stylesheets.
Source Location Tracking (CSSRule.prototype.location): Parsed CSS rules expose their source offsets ({ start: number, end: number, line: number, column: number, bodyStart?: number, bodyEnd?: number }) relative to the original source text via a non-enumerable location property on CSSRule.prototype (with 1-based line and column numbers), enabling source maps, DevTools coverage pruning, and refactoring tools without breaking standard IDL enumeration or serialization.
Legacy CSSRule.type Constants: Numeric type constants (STYLE_RULE = 1, MEDIA_RULE = 4, etc.) are retained on CSSRule instances and static constructors for backward compatibility, with modern rule types evaluating to 0.
CSSStyleDeclaration Host Integration: CSSStyleDeclaration supports a (parentRule?, onChange?) constructor signature and public onChange callback hook (temporarily setting decl.onChange = null suppresses callbacks when hydrating from host DOM style attributes). It also provides a full Proxy supporting camelCase (style.fontSize), kebab-case (style['font-size']), style.cssFloat, webkit* prefixes, exact case preservation on --customProperties, and WebIDL-compliant Object.keys(style) returning only indexed property names 0..length-1.
CSSSupportsRule Feature Evaluation: CSSSupportsRule.prototype.matches returns a boolean evaluating the condition text via the conditional rules engine per CSS Conditional 4/5.
Single Rule Model (CSSRule): The public Rule type is an alias for CSSRule. Custom at-rules parsed via the atRules option with parse() produce CSSAtRule instances (exported in src/entry/tools.ts) exposing .declarations (for declaration blocks) or .childRules (for rule blocks) and standard .cssText.
2. Houdini & WICG Parser API Layer (Modern & Experimental)
These APIs expose low-level parsing, property registration, and typed values defined in Houdini and CSS Values specifications.
Specifications Followed
CSS Typed OM Level 1: submodules/css-houdini-drafts/css-typed-om/Overview.bs
CSS Typed OM Level 2 / CSS Color API: submodules/css-houdini-drafts/css-typed-om-2/Overview.bs
CSS Properties and Values API Level 1: submodules/css-houdini-drafts/css-properties-values-api/Overview.bs
CSS Parser API (cssomnom/parser-api): Based on the WICG CSS Parser API draft.
CSS Values and Units Level 4: submodules/csswg-drafts/css-values-4/Overview.bs (Calculation trees, math functions, color models).
Interfaces & Methods
WICG Parser API (import { ... } from 'cssomnom/parser-api'):
String Boxing: The spec defines CSSToken as typedef (DOMString or CSSStyleValue or CSSParserValue) CSSToken;. We box raw strings in CSSParserToken instead of using raw string primitives.
Synchronous Execution: parseRule, parseDeclarationList, parseDeclaration, parseComponentValue, parseValue, parseValueList, and parseCommaValueList execute synchronously; parseStylesheet and parseRuleList accept strings or ReadableStreams and return a Promise.
Immutability: Parser rule and block properties (prelude, body, args) are mutable TypeScript arrays rather than FrozenArray.
Constructor Arguments: body is mandatory in CSSParserQualifiedRule constructor (constructor(prelude, body)).
CSS Values 4 Math Functions (CSSMathFunction): New math functions (sin(), cos(), abs(), etc.) are represented by CSSMathFunction. Its operator getter returns the function's identifier name (e.g. 'sin').
WebIDL Dictionary Bindings: Dictionary constraints and computationally independent initial value validations for CSS.registerProperty() are enforced natively in JavaScript.
CSSTransformComponent Inheritance: CSSTransformComponent inherits from CSSStyleValue, aligning with browser implementations (Blink, WebKit) and enabling reification from CSSStyleValue.parseAll() and StylePropertyMap.get().
Math Simplification & Calculation Tree Preservation: Calculation trees from CSSNumericValue.parse() and StylePropertyMap preserve CSSMathValue tree structures per css-values-4 #calc-internal rather than performing eager unit reduction at parse time.
Typed OM Color Property Reification: Per css-typed-om #reify-property, W3C Houdini Issue #689, and WPT conformance tests, color properties accessed via StylePropertyMap (styleMap.get('color'), etc.) reify as generic base CSSStyleValue objects (with currentcolor and grammar keywords like auto on caret-color reifying as CSSKeywordValue). CSSColorValue subclasses (CSSRGB, CSSHSL, etc.) are exposed via CSSColorValue.parse(), deferring property-level color reification to Level 2 in alignment with browser engines.
These standalone tree-shakeable functions and classes are exported from cssomnom (src/entry/tools.ts):
Functions & Classes
parse(css, options?): Direct parser returning a constructable CSSStyleSheet (cssomnom and cssomnom/parse).
getRules(root, RuleClass?): Depth-first pre-order collector returning CSSRule[] (or narrowed T[] when RuleClass is passed).
closestRule(rule, RuleClass): Walks strict rule.parentRule ancestors to find the nearest enclosing RuleClass instance.
resolveSelector(rule): Resolves CSS Nesting & combinators and relative selectors across enclosing CSSStyleRule and @scope ancestors into a canonical selector string.
parseSelectorAST(input, options?): Parses a selector string or CSSRule into a Selectors Level 4 SelectorList AST.
getDeclaredProperties(root, options?): Collects a Set<string> of all declared CSS property names across the stylesheet, including parent shorthands (border, border-color, outline, overflow, padding, margin, line-clamp, etc.) and @supports feature queries ({ includeSupports?: boolean }, default true).
getPropertyValues(target, property, options?): Returns all authored values for property in declaration order on a CSSRule or CSSStyleDeclaration, resolving logical↔physical property aliases, unexpanded var() shorthands, and same-rule progressive-enhancement fallbacks.
CSSAtRule: Custom at-rule representation created when ParserOptions.atRules is passed to parse().
API Surface Verification
The public API surface area is locked down and verified by api-surface.test.ts. Any additions or removals of public exports must be reflected in that test to ensure intentional API changes.
Parser Architecture & Upward ParseHooks
The core parser (src/parser.ts) exports standalone pure functions (parseStyleAttribute, consumeRule, consumeListOfRules, parseComponentValues, parseSelectorAST, validateCustomPropertyValue) for direct, tree-shakeable consumption by CSSOM and Typed OM modules. For upward extensibility without circular imports, ParseHooks (src/parse-hooks.ts) provides optional feature hooks (such as createStylePropertyMap, supports, and media query parsing/serialization) that higher-level modules register at bootstrap.
Intentional Non-Goals & Boundaries
No getComputedStyle() Support: We intentionally do not implement or expose window.getComputedStyle(). Resolving true computed styles requires a full visual rendering and layout engine (calculating font metrics, line heights, box-model geometry, viewport dimensions, and interaction states like :hover / :focus). In a server-side, headless Node.js environment, a partially correct getComputedStyle() produces subtle, misleading bugs and false confidence ("if it cannot be completely correct, partially correct is harmful"). Instead, cssomnom provides getCascadedStyle(element, rules) to resolve deterministic, declarative cascade and specificity order, leaving visual layout to real browsers.
No Layout Guessing in Computed Values: Layout-dependent used values (auto margins, auto min sizes, percentage positions against box size) return computed values. We do not infer layout context or fake used-value geometry without a browser layout engine.
Guidelines for Maintainers
When adding new features, clearly identify which layer they belong to.
Prefer implementing standard APIs (Houdini or CSSOM) over custom ones whenever possible.
Cite spec anchors in code comments for all standard implementations.
Web Platform Test (WPT) Conformance & Parity
cssomnom is evaluated against the official W3C Web Platform Tests (WPT) in pure Node.js across 8 major specification suites (CSSOM, Syntax, Nesting, Variables, Selectors, Media Queries, Cascade, and Typed OM).
W3C Standards Conformance: 93.7% (21,691 / 23,157 passed assertions across 1,882 test files).
Chrome 154 Parity: 93.7% pass rate across 28,773 common subtests evaluated against official wpt.fyi runs.