Registry / serialization / css-syntax-parser

css-syntax-parser

library1.5.1jsnpmunverified

The `css-syntax-parser` package provides a specialized JavaScript and TypeScript library for parsing and interpreting CSS value definition syntax as specified by MDN (Mozilla Developer Network). It generates an Abstract Syntax Tree (AST) that precisely details the structure, combinators, and multipliers present in a given CSS syntax string. Currently stable at version 1.5.1, the library does not specify a fixed release cadence but has seen ongoing development since its initial release. Its core differentiation lies in its precise adherence to the MDN syntax definition, offering programmatic access to the parsed structure including term types (e.g., `keyword`, `data-type`, `composed`), combinators (e.g., `|`, `&&`), and multipliers (e.g., `{1,4}`, `?`). This enables developers to validate, analyze, or generate CSS property values based on their defined grammar, which is a niche but critical use case for tooling and language servers.

serialization

npm install css-syntax-parser

github ↗package ↗

INSTALL

IMPORT

SIG · CSS-SYNTAX-PARSER

css-syntax-parser

serializationjavascriptv1.5.1

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.

resolveSyntax

✓ import { resolveSyntax } from 'css-syntax-parser'

✗ const resolveSyntax = require('css-syntax-parser')

While CommonJS `require` works, ESM `import` is the recommended and modern approach, especially in TypeScript projects.

resolveSyntaxByName

✓ import { resolveSyntaxByName } from 'css-syntax-parser'

Used for resolving syntax definitions by CSS property name, often requiring the `recursive: true` option for full resolution.

TermType

✓ import { TermType } from 'css-syntax-parser'

Import TermType enum and other specific AST node types (e.g., `BracketsTerm`, `ComposedTerm`) for type-safe manipulation in TypeScript.

This quickstart demonstrates parsing a CSS value definition, accessing its properties, and safely type-narrowing the resulting AST nodes in TypeScript.

import { resolveSyntax, Term, TermType, BracketsTerm, ComposedTerm, DataTypeTerm, TermMultiplier } from 'css-syntax-parser'; const syntax: Term = resolveSyntax('[ <length> | <percentage> | auto ]{1,4}'); console.log(`Parsed syntax type: ${syntax.type}`); if (syntax.type === TermType.BRACKETS) { const brackets: BracketsTerm = syntax as BracketsTerm; console.log(`Bracket multiplier: ${brackets.multiplier}`); if (brackets.multiplier === TermMultiplier.RANGE) { console.log(`Range: min=${brackets.range.min}, max=${brackets.range.max}`); } if (brackets.content.type === TermType.COMPOSED) { const content: ComposedTerm = brackets.content as ComposedTerm; console.log(`Content type: ${content.type}, combinator: ${content.combinator}`); const child1 = content.children[1]; if (child1.type === TermType.DATA_TYPE) { const dataTypeChild: DataTypeTerm = child1 as DataTypeTerm; console.log(`Second child: type=${dataTypeChild.type}, name=${dataTypeChild.name}, nonTerminal=${dataTypeChild.nonTerminal}`); } } }

Debug

Known issues

gotchaWhen working with the parsed AST in TypeScript, properties of a `Term` (the base interface) must often be accessed after type narrowing (e.g., checking `term.type === TermType.BRACKETS`) or using type assertions to access specific sub-interface properties.

fix

Use `if (term.type === TermType.BRACKETS)` blocks or type assertions like `(term as BracketsTerm).content` to safely access properties specific to a particular Term type.

affects: >=1.0.0

gotchaThe `resolveSyntaxByName` method with `recursive: false` will not fully resolve nested data types (e.g., `<color>`). For comprehensive ASTs, always pass `true` as the second argument.

fix

Ensure `resolveSyntaxByName('propertyName', true)` is used when a fully expanded syntax tree is required, especially for complex CSS properties.

affects: >=1.0.0

gotchaProviding malformed or non-MDN-compliant CSS value definition syntax to `resolveSyntax` can lead to unexpected AST structures or parsing errors, as the parser is designed for a specific grammar.

fix

Validate input syntax strings against MDN's CSS value definition syntax or implement robust error handling (e.g., try-catch blocks) around parser calls. The library is not a general-purpose CSS parser.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: resolveSyntax is not a function

The module was imported incorrectly, possibly using a default import or a CommonJS `require` call in an ESM-only context.

fix

Ensure you are using named imports for ESM: `import { resolveSyntax } from 'css-syntax-parser';` or the correct `require` syntax for CommonJS environments.

Property 'name' does not exist on type 'Term'. Property 'name' does not exist on type 'BracketsTerm'.

Attempting to access a property specific to a derived `Term` type (like `DataTypeTerm`) directly from a generic `Term` or an incorrect `Term` type without proper type narrowing.

fix

Use TypeScript type guards to narrow the type before accessing specific properties, e.g., `if (term.type === TermType.DATA_TYPE) { console.log(term.name); }`.

Syntax Error: Unexpected token '<' at position 0

The input string provided to `resolveSyntax` does not conform to the expected MDN CSS value definition syntax, causing the parser to fail at the first unexpected character.

fix

Review the input string for typos or incorrect grammar. The parser strictly adheres to the specified syntax and is not tolerant of general CSS syntax errors.

Upgrade

Version history

1.5.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/zanomate/css-syntax-parser ↗

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