w3c-validate-css

Validate CSS offline using the official W3C css-validator.jar

Why? modern build tools can introduce CSS bugs. w3c-validate-css runs locally and prints concise, clickable errors with line numbers using the same rules as the online W3C validator, but entirely offline.

CLI

The easiest way to use this is from the cli using npx, for example:

# Validate a folder, fail only on errors, tolerate a property
npx w3c-validate-css --target dist/css --errors-only --tolerate "pointer-events"

Output:

✗ dist/app.css
    dist/app.css:14:8 - Parse Error: Declaration dropped
    dist/app.css:45 - Unknown pseudo-element or pseudo-class :where()
✓ dist/reset.css

Exits with code 1 if validation fails.

options

Flag	Alias	Value	Default	Description
--target	-t	<path>		File or folder to validate (required)
--profile	-p	css3|css21|css1|svg	css3	Validation profile
--warnings	-w	0|1|2	2	Warning level: 0 none, 1 normal, 2 all
--deprecations	-d		false	Include deprecation warnings
--errors-only	-e		false	Show only errors; ignore warnings
--json			false	Output JSON summary
--tolerate		"prop1,prop2"	""	Downgrade properties to warnings

Node module

npm i w3c-validate-css --save-dev

var validateCss = require('w3c-validate-css');

validateCss('dist/', {
  profile: 'css3',
  warningLevel: 2,
  showDeprecations: false,
  errorsOnly: false,
  json: false
})
.then(function (summary) {
  if (summary.failed > 0) process.exitCode = 1;
})
.catch(function (err) {
  console.error('w3c-validate-css error:', err && err.message ? err.message : String(err));
});

JSON result:

{
  "passed": 1,
  "failed": 1,
  "results": [
    {
      "file": "dist/styles.css",
      "ok": false,
      "errors": [{ "line": 14, "col": 8, "msg": "Parse Error: Declaration dropped" }],
      "warnings": [{ "line": 45, "col": 0, "msg": "Unknown pseudo-element or pseudo-class :where()" }]
    },
    { "file": "dist/reset.css", "ok": true, "errors": [], "warnings": [] }
  ]
}

GitHub Action

name: css-validate
on: [push, pull_request]
jobs:
  css-validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npx w3c-validate-css --target dist/ --json > css-report.json
      - uses: actions/upload-artifact@v4
        with:
          name: css-report
          path: css-report.json

License

MIT License © Orca Scan - a barcode app with simple barcode tracking APIs.