csstree
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-validatorproduces 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-validatordoesn'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-validatorUsage
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: '<line-width> || <line-style> || <color>',
// 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: <line-width> || <line-style> || <color>\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:<?xml version="1.0" encoding="utf-8"?> <checkstyle version="4.3"> <file name="{filename}"> <error line="{line}" column="{column}" severity="error" message="{message}" source="csstree-validator" /> </file> </checkstyle>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 withcsstreeValidatoras a global variable.<script src="node_modules/csstree-validator/dist/csstree-validator.js"></script> <script> const errors = csstreeValidator.validate('.some { css: source }'); </script>ES Module (
dist/csstree-validator.esm.js) – Minified ES module.<script type="module"> import { validate } from 'csstree-validator/dist/csstree-validator.esm.js'; const errors = validate('.some { css: source }'); </script>
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:
<!-- ESM -->
<script type="module">
import * as csstreeValidator from 'https://cdn.jsdelivr.net/npm/csstree-validator';
// or
import * as csstreeValidator from 'https://unpkg.com/csstree-validator';
</script>
<!-- IIFE with csstreeValidator as a global -->
<script src="https://cdn.jsdelivr.net/npm/csstree-validator/dist/csstree-validator.js"></script>
<!-- or -->
<script src="https://unpkg.com/csstree-validator/dist/csstree-validator.js"></script>Note: Helpers are not available in the browser version.
Command-Line Interface (CLI)
Install globally via npm:
npm install -g csstree-validatorRun the validator on a CSS file:
csstree-validator /path/to/style.cssDisplay help:
csstree-validator -hUsage:
csstree-validator [fileOrDir] [options]
Options:
-h, --help Output usage information
-r, --reporter <nameOrFile> Output formatter: console (default), checkstyle, json, gnu
or <path to a module>
-v, --version Output versionCustom Reporters
In addition to the built-in reporters, you can specify a custom reporter by providing the path to a module or package. The module should export a single function that takes the validation result object and returns a string:
export default function(result) {
let output = '';
for (const [filename, errors] of result) {
// Generate custom output
}
return output;
}
// For CommonJS:
// module.exports = function(result) { ... }The reporter option accepts:
- ESM Module – Full path to a file with a
.jsextension. - CommonJS Module – Full path to a file with a
.cjsextension. - ESM Package – Package name or full path to a module within the package.
- CommonJS Package – Package name or path to a module within the package.
- Dual Package – Package name or full path to a module within the package.
The resolution algorithm checks the reporter value in the following order:
- If it's a path to a file (relative to
process.cwd()), use it as a module. - If it's a path to a package module (relative to
process.cwd()), use the package's module. - Otherwise, the value should be the name of one of the predefined reporters, or an error will be raised.
Integrations
Plugins that use csstree-validator:
License
MIT