@tabnas/css

A Tabnas grammar plugin that parses CSS into a faithful abstract syntax tree (the reworkcss/css model): ordered, typed nodes that preserve declaration order, duplicate properties, rule types, and comments.

Install

npm install @tabnas/parser @tabnas/jsonic @tabnas/css

Requires @tabnas/parser >= 2 and @tabnas/jsonic >= 2 as peer dependencies.

One example

The plugin layers onto a Tabnas engine that already has the jsonic grammar:

import { Tabnas } from '@tabnas/parser'
import { jsonic } from '@tabnas/jsonic'
import { Css } from '@tabnas/css'

const c = new Tabnas().use(jsonic).use(Css)

c.parse('a { color: red }')
// => { type: 'stylesheet', rules: [ { type: 'rule', selectors: ['a'], declarations: [ { type: 'declaration', property: 'color', value: 'red' } ] } ] }

Build the instance once and reuse it — constructing the grammar is the expensive part.

Options

The plugin takes two options through its second use() argument, both defaulting to false:

• lowercaseProperties — lowercase declaration property names.
• position — attach a position (1-based start/end line and column) to every node.

import { Tabnas } from '@tabnas/parser'
import { jsonic } from '@tabnas/jsonic'
import { Css } from '@tabnas/css'

const c = new Tabnas().use(jsonic).use(Css, { position: true })

CSS Nesting

A style rule or an at-rule may appear inside another style rule's declaration block. The nested node is appended to the parent's declarations array, interleaved with declarations in source order:

const c = new Tabnas().use(jsonic).use(Css)

c.parse('a { color: red; & b { top: 0 } }').rules[0].declarations[1]
// => { type: 'rule', selectors: ['& b'], declarations: [ { type: 'declaration', property: 'top', value: '0' } ] }

Documentation

Full documentation follows the Diátaxis framework:

• Tutorial — a guided first parse, start to finish.
• How-to guide — short recipes for individual tasks.
• Reference — the public API, every option, and the complete AST node reference.
• Concepts — how the plugin reshapes the engine, and why.

For the Go port, see ../go/README.md.

Grammar diagram

The grammar is defined in the top-level css-grammar.jsonic and embedded into this implementation (and the Go port) by embed-grammar.js during the build.

The installed grammar as a railroad/syntax diagram, generated with @tabnas/railroad:

A vertical ASCII version is in doc/grammar.txt.

License

Copyright (c) 2025 Richard Rodger and other contributors, MIT License.