{"id":15993,"library":"css-syntax-parser","title":"CSS Syntax Parser","description":"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.","status":"active","version":"1.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/zanomate/css-syntax-parser","tags":["javascript","css","mdn","syntax","parser","typescript"],"install":[{"cmd":"npm install css-syntax-parser","lang":"bash","label":"npm"},{"cmd":"yarn add css-syntax-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add css-syntax-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` works, ESM `import` is the recommended and modern approach, especially in TypeScript projects.","wrong":"const resolveSyntax = require('css-syntax-parser')","symbol":"resolveSyntax","correct":"import { resolveSyntax } from 'css-syntax-parser'"},{"note":"Used for resolving syntax definitions by CSS property name, often requiring the `recursive: true` option for full resolution.","symbol":"resolveSyntaxByName","correct":"import { resolveSyntaxByName } from 'css-syntax-parser'"},{"note":"Import TermType enum and other specific AST node types (e.g., `BracketsTerm`, `ComposedTerm`) for type-safe manipulation in TypeScript.","symbol":"TermType","correct":"import { TermType } from 'css-syntax-parser'"}],"quickstart":{"code":"import { resolveSyntax, Term, TermType, BracketsTerm, ComposedTerm, DataTypeTerm, TermMultiplier } from 'css-syntax-parser';\n\nconst syntax: Term = resolveSyntax('[ <length> | <percentage> | auto ]{1,4}');\n\nconsole.log(`Parsed syntax type: ${syntax.type}`);\n\nif (syntax.type === TermType.BRACKETS) {\n    const brackets: BracketsTerm = syntax as BracketsTerm;\n    console.log(`Bracket multiplier: ${brackets.multiplier}`);\n\n    if (brackets.multiplier === TermMultiplier.RANGE) {\n        console.log(`Range: min=${brackets.range.min}, max=${brackets.range.max}`);\n    }\n\n    if (brackets.content.type === TermType.COMPOSED) {\n        const content: ComposedTerm = brackets.content as ComposedTerm;\n        console.log(`Content type: ${content.type}, combinator: ${content.combinator}`);\n\n        const child1 = content.children[1];\n        if (child1.type === TermType.DATA_TYPE) {\n            const dataTypeChild: DataTypeTerm = child1 as DataTypeTerm;\n            console.log(`Second child: type=${dataTypeChild.type}, name=${dataTypeChild.name}, nonTerminal=${dataTypeChild.nonTerminal}`);\n        }\n    }\n}","lang":"typescript","description":"This quickstart demonstrates parsing a CSS value definition, accessing its properties, and safely type-narrowing the resulting AST nodes in TypeScript."},"warnings":[{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `resolveSyntaxByName('propertyName', true)` is used when a fully expanded syntax tree is required, especially for complex CSS properties.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Providing 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are using named imports for ESM: `import { resolveSyntax } from 'css-syntax-parser';` or the correct `require` syntax for CommonJS environments.","cause":"The module was imported incorrectly, possibly using a default import or a CommonJS `require` call in an ESM-only context.","error":"TypeError: resolveSyntax is not a function"},{"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); }`.","cause":"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.","error":"Property 'name' does not exist on type 'Term'. Property 'name' does not exist on type 'BracketsTerm'."},{"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.","cause":"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.","error":"Syntax Error: Unexpected token '<' at position 0"}],"ecosystem":"npm"}