@tbela99/css-parser

css-parser

CSS parser for node and the browser

Installation

$ npm install @tbela99/css-parser

Features

• fault tolerant parser, will try to fix invalid tokens according to the CSS syntax module 3 recommendations.
• efficient minification, see benchmark
• automatically generate nested css rules
• compute css shorthands. see the list below
• expand nested css
• works the same way in node and web browser

Transform

Parse and render css in a single pass.

Usage

transform(css, transformOptions = {})

Example

import {transform} from '@tbela99/css-parser';

const {ast, code, errors, stats} = await transform(css, {minify: true, resolveImport: true, cwd: 'files/css'});

TransformOptions

Include ParseOptions and RenderOptions

ParseOptions

• src: string, optional. css file location to be used with sourcemap.
• minify: boolean, optional. default to true. optimize ast.
• nestingRules: boolean, optional. automatically generated nested rules.
• removeEmpty: boolean, remove empty nodes from the ast.
• location: boolean, optional. includes node location in the ast, required for sourcemap generation.
• cwd: string, optional. the current working directory. when specified url() are resolved using this value
• resolveImport: boolean, optional. replace @import node by the content of the referenced stylesheet.
• resolveUrls: boolean, optional. resolve css url() according to the parameters 'src' and 'cwd'

RenderOptions

• minify: boolean, optional. default to true. minify css output.
• indent: string, optional. css indention string. uses space character by default.
• newLine: string, new line character.
• removeComments: boolean, remove comments in generated css.
• preserveLicense: boolean, force preserving comments starting with '/*!' when minify is enabled.
• colorConvert: boolean, convert colors to hex.

Parsing

Usage

parse(css, parseOptions = {})

Example

const {ast, errors, stats} = await parse(css);

Rendering

Usage

render(ast, RenderOptions = {});

Example

import {render} from '@tbela99/css-parser';

// minified
const {code, stats} = render(ast, {minify: true});

console.log(code);

Node Walker

import {walk} from '@tbela99/css-parser';

for (const {node, parent, root} of walk(ast)) {
    
    // do somehting
}

Exports

There are several ways to import the library into your application.

Node exports

import as a module

import {transform} from '@tbela99/css-parser';

// ...

import as a CommonJS module

const {transform} = require('@tbela99/css-parser/cjs');

// ...

Web export

Programmatic import

import {transform} from '@tbela99/css-parser/web';

// ...

Javascript module

<script src="dist/web/index.js" type="module"></script>

Single JavaScript file

<script src="dist/index-umd-web.js"></script>

Example 1

Automatic CSS Nesting

CSS

table.colortable td {
  text-align:center;
}
table.colortable td.c {
  text-transform:uppercase;
}
table.colortable td:first-child, table.colortable td:first-child+td {
  border:1px solid black;
}
table.colortable th {
  text-align:center;
  background:black;
  color:white;
}

Javascript

import {parse, render} from '@tbela99/css-parser';


const options = {minify: true, nestingRules: true};

const {code} = await parse(css, options).then(result => render(result.ast, {minify: false}));
//
console.debug(code);

Result

table.colortable {
 & td {
  text-align: center;
  &.c {
   text-transform: uppercase
  }
  &:first-child,&:first-child+td {
   border: 1px solid #000
  }
 }
 & th {
  text-align: center;
  background: #000;
  color: #fff
 }
}

Example 2

Nested CSS Expansion

CSS

table.colortable {
 & td {
  text-align: center;
  &.c {
   text-transform: uppercase
  }
  &:first-child,&:first-child+td {
   border: 1px solid #000
  }
 }
 & th {
  text-align: center;
  background: #000;
  color: #fff
 }
}

Javascript

import {parse, render} from '@tbela99/css-parser';


const options = {minify: true};

const {code} = await parse(css, options).then(result => render(result.ast, {minify: false, expandNestingRules: true}));
//
console.debug(code);

Result

table.colortable td {
  text-align:center;
}
table.colortable td.c {
  text-transform:uppercase;
}
table.colortable td:first-child, table.colortable td:first-child+td {
  border:1px solid black;
}
table.colortable th {
  text-align:center;
  background:black;
  color:white;
}

AST

Comment

• typ: string 'Comment'
• val: string, the comment

Declaration

• typ: string 'Declaration'
• nam: string, declaration name
• val: array of tokens

Rule

• typ: string 'Rule'
• sel: string, css selector
• chi: array of children

AtRule

• typ: string 'AtRule'
• nam: string. AtRule name
• val: rule prelude

AtRuleStyleSheet

• typ: string 'Stylesheet'
• chi: array of children

Minification

• merge identical rules
• merge adjacent rules
• minify colors
• minify numbers and Dimensions tokens
• compute shorthand: see the list below
• remove redundant declarations
• conditionally unwrap :is()
• automatic css nesting
• automatically wrap selectors using :is()
• multi-level shorthand properties (border - [border-width, border-color, border-style, etc.]) https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties
• avoid reparsing (declarations, selectors, at-rule)
• node and browser versions
• decode and replace utf-8 escape sequence

Computed shorthands

• background
• border
• border-bottom
• border-color
• border-left
• border-radius
• border-right
• border-style
• border-top
• border-width
• font
• inset
• margin
• outline
• overflow
• padding
• text-decoration

Performance

• flatten @import

Changelog

v0.0.1

Minification

• [x] merge identical rules
• [x] merge adjacent rules
• [x] minify colors
• [x] minify numbers and Dimensions tokens
• [x] compute shorthand: see the list below
• [x] remove redundant declarations
• [x] simple shorthand properties (padding, margin, etc). must have all required properties
• [x] complex shorthand properties (background, font, etc.). may have optional properties
• [x] conditionally unwrap :is()
• [x] automatic css nesting
• [x] automatically wrap selectors using :is()
• [x] multi-level shorthand properties ( border - [border-width, border-color, border-style, etc.]) https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties
• [x] avoid reparsing (declarations, selectors, at-rule)
• [x] node and browser versions
• [x] decode and replace utf-8 escape sequence

Computed shorthands

• [x] background
• [x] border
• [x] border-bottom
• [x] border-color
• [x] border-left
• [x] border-radius
• [x] border-right
• [x] border-style
• [x] border-top
• [x] border-width
• [x] font
• [x] inset
• [x] margin
• [x] outline
• [x] overflow
• [x] padding
• [x] text-decoration

Performance

• [x] flatten @import

Error handling

• [x] parse bad comments / cdo comments
• [x] parse bad string 1
• [x] parse bad string 2
• [x] parse empty declaration
• [x] parse unclosed rule
• [x] parse unclosed at-rule
• [x] parse bad import

Testing

• [x] node tests
• [x] browser tests

Code Coverage

• [x] node
• [x] browser