CSSTree Validator

CSS Validator built on CSSTree.

Technically, the package utilizes the capabilities of CSSTree to match CSS syntaxes to various parts of your code and generates a list of errors, if any.

> Note: If csstree-validator produces false positives or false negatives, such as unknown properties or invalid values for a property, please report the issue to the CSSTree issue tracker.

> Note: CSSTree currently doesn't support selector syntax matching; therefore, csstree-validator doesn't support it either. Support for selector validation will be added once it is available in CSSTree.

Installation

Install the package via npm:

npm install csstree-validator

Usage

You can validate a CSS string or a CSSTree AST:

import { validate } from 'csstree-validator';
// For CommonJS:
// const { validate } = require('csstree-validator');

const filename = 'demo/example.css';
const css = '.class { pading: 10px; border: 1px super red }';

console.log(validate(css, filename));
// Output:
// [
//   SyntaxError [SyntaxReferenceError]: Unknown property `pading` {
//     reference: 'pading',
//     property: 'pading',
//     offset: 9,
//     line: 1,
//     column: 10
//   },
//   SyntaxError [SyntaxMatchError]: Mismatch {
//     message: 'Invalid value for `border` property',
//     rawMessage: 'Mismatch',
//     syntax: ' ||  || ',
//     css: '1px super red',
//     mismatchOffset: 4,
//     mismatchLength: 5,
//     offset: 35,
//     line: 1,
//     column: 36,
//     loc: { source: 'demo/example.css', start: [Object], end: [Object] },
//     property: 'border',
//     details: 'Mismatch\n' +
//       '  syntax:  ||  || \n' +
//       '   value: 1px super red\n' +
//       '  ------------^'
//   }
// ]

Alternatively, you can use helper functions to validate a file or directory and utilize one of the built-in reporters:

import { validateFile, reporters } from 'csstree-validator';

const result = validateFile('./path/to/style.css');
console.log(reporters.checkstyle(result));

Validation Methods

• validate(css, filename)
• validateAtrule(node)
• validateAtrulePrelude(atrule, prelude, preludeLoc)
• validateAtruleDescriptor(atrule, descriptor, value, descriptorLoc)
• validateDeclaration(property, value, valueLoc)
• validateRule(node)

Helpers

> Note: Helpers are not available in browser environments as they rely on Node.js APIs.

All helper functions return an object where the key is the path to a file and the value is an array of errors. The result object is iterable (has Symbol.iterator) and can be used with for...of loops or the spread operator.

Example:

const result = validateFile('path/to/file.css');

for (const [filename, errors] of result) {
  // Process errors
}

Available helper functions:

• validateString(css, filename)
• validateDictionary(dictionary)
• validateFile(filename)
• validatePath(searchPath, filter)
• validatePathList(pathList, filter)

Reporters

CSSTree Validator provides several built-in reporters to convert validation results into different formats:

• console – Human-readable text suitable for console output.

• json – Converts errors into a unified JSON array of objects:

  type ErrorEntry = {
    name: string; // Filename
    line: number;
    column: number;
    atrule?: string;
    descriptor?: string;
    property?: string;
    message: string;
    details?: any;
  }
  

• checkstyle – Checkstyle XML report format:

• gnu – GNU error log format:

  "FILENAME":LINE.COLUMN: error: MESSAGE
  "FILENAME":START_LINE.COLUMN-END_LINE.COLUMN: error: MESSAGE
  

Example usage:

import { validate, reporters } from 'csstree-validator';

const css = '.class { padding: 10px; color: red; }';
const result = validate(css, 'example.css');

console.log(reporters.json(result));
// Output:
// [
//   { "name": 'example.css', ... },
//   { "name": 'example.css', ... },
//   ...
// ]

Browser Usage

CSSTree Validator can be used in browser environments using the available bundles:

• IIFE Bundle (dist/csstree-validator.js) – Minified IIFE with csstreeValidator as a global variable.

• ES Module (dist/csstree-validator.esm.js) – Minified ES module.

You can also use a CDN service like unpkg or jsDelivr. By default, the ESM version is exposed for short paths. For the IIFE version, specify the full path to the bundle:

Note: Helpers are not available in the browser version.

Command-Line Interface (CLI)

Install globally via npm:

npm install -g csstree-validator

Run the validator on a CSS file:

csstree-validator /path/to/style.css

Display help:

csstree-validator -h

Usage:

    csstree-validator [fileOrDir] [options]

Options:

    -h, --help                     Output usage information
    -r, --reporter     Output formatter: console (default), checkstyle, json, gnu
                                   or