css-tree

What is css-tree?

The css-tree npm package is a tool for parsing and manipulating CSS. It allows users to parse CSS strings into an abstract syntax tree (AST), walk over nodes in the tree, generate CSS strings, and more. It is useful for tasks such as CSS minification, linting, and transformation.

What are css-tree's main functionalities?

Parsing CSS to AST

This feature allows you to parse a CSS string and convert it into an abstract syntax tree (AST) for further manipulation or analysis.

const csstree = require('css-tree');
const ast = csstree.parse('.example { color: red; }');

Walking the AST

This feature enables you to traverse the AST and apply functions or extract information from specific nodes.

csstree.walk(ast, function(node) {
  if (node.type === 'ClassSelector') {
    console.log(node.name);
  }
});

Generating CSS from AST

After manipulating the AST, you can generate a CSS string from the modified AST, which can be used in stylesheets or injected into web pages.

const modifiedAST = csstree.parse('.example { color: blue; }');
const css = csstree.generate(modifiedAST);

Minifying CSS

css-tree can be used to minify CSS by parsing it with compression options and then translating the AST back to a CSS string.

const compressedCSS = csstree.translate(csstree.parse('.example { color: red; }', { compress: true }));

Other packages similar to css-tree

postcss

PostCSS is a tool for transforming CSS with JavaScript plugins. It can do similar tasks as css-tree, such as parsing, walking the AST, and generating CSS. PostCSS is plugin-based, which makes it more extensible and allows for a wide range of transformations.

sass

Sass is a preprocessor scripting language that is interpreted or compiled into CSS. It offers more syntactic features compared to css-tree, such as variables, nesting, and mixins, but it is not primarily focused on parsing and manipulating existing CSS.

less

Less is another CSS pre-processor, similar to Sass, that extends the capabilities of CSS with dynamic behavior such as variables, mixins, operations, and functions. Less and css-tree serve different purposes, with Less focusing on writing CSS in a more functional way and css-tree on parsing and manipulation.

clean-css

clean-css is a fast and efficient CSS optimizer for Node.js and the browser. It focuses on minification, which is one of the features of css-tree, but does not provide a general-purpose CSS parsing and manipulation API.

README

CSSTree

Fast detailed CSS parser

Work in progress. Project in alpha stage since AST format is subject to change.

Docs and tools:

• AST Explorer – explore CSSTree AST format with zero setup
• CSS syntax reference
• CSS syntax validator

Related projects:

• csstree-validator – NPM package to validate CSS
• stylelint-csstree-validator – plugin for stylelint to validate CSS
• Grunt plugin
• Gulp plugin
• Sublime plugin
• VS Code plugin
• Atom plugin

Install

> npm install css-tree

Usage

var csstree = require('css-tree');

csstree.walk(csstree.parse('.a { color: red; }'), function(node) {
  console.log(node.type);
});
// StyleSheet
// Rule
// SelectorList
// Selector
// Class
// Block
// Declaration
// Value
// Identifier

API

parse(source[, options])

Parses CSS to AST.

NOTE: Currenly parser omits redundant separators, spaces and comments (except exclamation comments, i.e. /*! comment */) on AST build.

Options:

• context String – parsing context, useful when some part of CSS is parsing (see below)
• atrule String – make sense for atruleExpression context to apply some atrule specific parse rules
• property String – make sense for value context to apply some property specific parse rules
• positions Boolean – should AST contains node position or not, store data in info property of nodes (false by default)
• filename String – filename of source that adds to info when positions is true, uses for source map generation (<unknown> by default)
• line Number – initial line number, useful when parse fragment of CSS to compute correct positions
• column Number – initial column number, useful when parse fragment of CSS to compute correct positions

Contexts:

• stylesheet (default) – regular stylesheet, should be suitable in most cases
• atrule – at-rule (e.g. @media screen, print { ... })
• atruleExpression – at-rule expression (screen, print for example above)
• rule – rule (e.g. .foo, .bar:hover { color: red; border: 1px solid black; })
• selectorList – selector group (.foo, .bar:hover for rule example)
• selector – selector (.foo or .bar:hover for rule example)
• block – block with curly braces ({ color: red; border: 1px solid black; } for rule example)
• declarationList – block content w/o curly braces (color: red; border: 1px solid black; for rule example), useful to parse HTML style attribute value
• declaration – declaration (color: red or border: 1px solid black for rule example)
• value – declaration value (red or 1px solid black for rule example)

// simple parsing with no options
var ast = csstree.parse('.example { color: red }');

// parse with options
var ast = csstree.parse('.foo.bar', {
    context: 'simpleSelector',
    positions: true
});

clone(ast)

Make an AST node deep copy.

var orig = csstree.parse('.test { color: red }');
var copy = csstree.clone(orig);

csstree.walk(copy, function(node) {
    if (node.type === 'Class') {
        node.name = 'replaced';
    }
});

console.log(csstree.translate(orig));
// .test{color:red}
console.log(csstree.translate(copy));
// .replaced{color:red}

translate(ast)

Converts AST to string.

var ast = csstree.parse('.test { color: red }');
console.log(csstree.translate(ast));
// > .test{color:red}

translateWithSourceMap(ast)

The same as translate() but also generates source map (nodes should contain positions in info property).

var ast = csstree.parse('.test { color: red }', {
    filename: 'my.css',
    positions: true
});
console.log(csstree.translateWithSourceMap(ast));
// { css: '.test{color:red}', map: SourceMapGenerator {} }

walk(ast, handler)

Visits each node of AST in natural way and calls handler for each one. handler receives three arguments:

• node – current AST node
• item – node wrapper when node is a list member; this wrapper contains references to prev and next nodes in list
• list – reference to list when node is a list member; it's useful for operations on list like remove() or insert()

Context for handler an object, that contains references to some parent nodes:

• root – refers to ast root node (actually it's a node passed to walker function)
• stylesheet – refers to StyleSheet node, usually it's a root node
• atruleExpression – refers to AtruleExpression node if any
• rule – refers to closest Rule node if any
• selector – refers to SelectorList node if any
• block - refers to closest Block node if any
• declaration – refers to Declaration node if any
• function – refers to closest Function, PseudoClass or PseudoElement node if current node inside one of them

// collect all urls in declarations
var csstree = require('./lib/index.js');
var urls = [];
var ast = csstree.parse(`
  @import url(import.css);
  .foo { background: url('foo.jpg'); }
  .bar { background-image: url(bar.png); }
`);

csstree.walk(ast, function(node) {
    if (this.declaration !== null && node.type === 'Url') {
        var value = node.value;

        if (value.type === 'Raw') {
            urls.push(value.value);
        } else {
            urls.push(value.value.substr(1, value.value.length - 2));
        }
    }
});

console.log(urls);
// [ 'foo.jpg', 'bar.png' ]

walkUp(ast, handler)

Same as walk() but visits nodes in down-to-top order. Useful to process deepest nodes and then their parents.

var csstree = require('css-tree');
var ast = csstree.parse('.a { color: red; }');

csstree.walk(ast, function(node) {
  console.log(node.type);
});
// StyleSheet
// Rule
// SelectorList
// Selector
// Class
// Block
// Declaration
// Value
// Identifier

csstree.walkUp(ast, function(node) {
  console.log(node.type);
});
// Class
// Selector
// SelectorList
// Identifier
// Value
// Declaration
// Block
// Rule
// StyleSheet

walkRules(ast, handler)

Same as walk() but visits Rule and Atrule nodes only.

walkRulesRight(ast, handler)

Same as walkRules() but visits nodes in reverse order (from last to first).

walkDeclarations(ast, handler)

Visit all declarations.

License

MIT

Syntax matching use mdn/data by Mozilla Contributors

Changelog

1.0.0-alpha14 (February 3, 2017)

• Implemented DeclarationList, MediaQueryList, MediaQuery, MediaFeature and Ratio node types
• Implemented declarationList context (useful to parse HTML style attribute content)
• Implemented custom consumers for @import, @media, @page and @supports at-rules
• Implemented atrule option for parse() config, is used for atruleExpession context to specify custom consumer for at-rule if any
• Added Scanner#skipWS(), Scanner#eatNonWS(), Scanner#consume() and Scanner#consumeNonWS() helper methods
• Added custom consumers for known functional-pseudos, consume unknown functional-pseudo content as balanced Raw
• Allowed any PseudoElement to be a functional-pseudo (#33)
• Improved walker implementations to reduce GC thrashing by reusing cursors
• Changed Atrule.block to contain a Block node type only if any
• Changed Block.loc positions to include curly brackets
• Changed Atrule.expression to store a null if no expression
• Changed parser to use StyleSheet node type only for top level node (when context is stylesheet, that's by default)
• Changed Parentheses, Brackets and Function consumers to use passed sequence reader instead of its own
• Changed Value and AtruleExpression consumers to use common sequence reader (that reader was used by Value consumer before)
• Changed default sequence reader to exclude storage of spaces around Comma
• Changed processing of custom properties:
  • Consume declaration value as balanced Raw
  • Consume var() fallback value as balanced Raw
  • Validate first argument of var() starts with double dash
  • Custom property's value and fallback includes spaces around
• Fixed Nth to have a loc property
• Fixed SelectorList.loc and Selector.loc positions to exclude spaces
• Fixed issue Browserify build fail with default-syntax.json is not found error (#32, @philschatz)
• Disallowed Type selector starting with dash (parser throws an error in this case now)
• Disallowed empty selectors for Rule (not sure if it's correct but looks reasonable)
• Removed >> combinator support until any browser support (no signals about that yet)
• Removed PseudoElement.legacy property
• Removed special case for :before, :after, :first-letter and :first-line to represent them as PseudoElement, now those pseudos are represented as PseudoClass nodes
• Removed deprecated Syntax#match() method
• Parser was splitted into modules and related changes, one step closer to an extensible parser
• Various fixes and improvements, all changes have negligible impact on performance