sitecore-lint

Static analysis for Sitecore serialized items — ESLint for your Sitecore repository.

Installation

npm install -D sitecore-lint

Quick start

Zero-config mode

sitecore-lint --sitecore-json src/sitecore.json

Config-file mode

sitecore-lint --config .sitecore-lint.json

Config files are auto-discovered by walking up from the current directory when --config is omitted. Supported formats: .sitecore-lint.json, .sitecore-lint.yml, .sitecore-lint.yaml, .sitecore-lint.js.

Config file reference

{
  "extends": ["sitecore-lint/configs/recommended"],
  "sources": ["items/**/*.yml"],
  "modules": ["modules/**/*.module.json"],
  "iar": ["artifacts/items.master.items.dat"],
  "plugins": ["@sitecore-lint/plugin-sxa", "@sitecore-lint/plugin-jss"],
  "rules": {
    "helix/layer-dependency": "error",
    "sitecore/max-versions": ["warning", { "maxVersions": 5 }],
    "sitecore/template-name-convention": "off"
  }
}

| Field | Type | Description | | -------------- | ---------- | ------------------------------------------------------------------------------------------- | | extends | string[] | Shareable config presets. Processed left-to-right; your rules always win. | | sources | string[] | Glob patterns for serialized YAML item files (relative to the config file) | | sitecoreJson | string | Path to sitecore.json — use instead of sources for zero-config discovery | | modules | string[] | Glob patterns for .module.json files — enables module-path and module-reference rules | | iar | string[] | Glob patterns for IAR .dat binary item archives | | plugins | string[] | Plugin package names or relative paths resolved via require() | | rules | object | Per-rule severity or option overrides |

Rule configuration formats

Severity string:

{ "rules": { "helix/layer-dependency": "error" } }

Tuple [severity, options]:

{ "rules": { "sitecore/max-versions": ["warning", { "maxVersions": 5 }] } }

Accepted severity values: "error" · "warning" · "info" · "off"

Built-in shareable presets

| Preset | Description | | ----------------------------------- | ---------------------------------------- | | sitecore-lint/configs/recommended | Sensible defaults for all built-in rules | | sitecore-lint/configs/strict | All rules promoted to error | | sitecore-lint/configs/all | Every rule enabled at warning |

CLI reference

Usage: sitecore-lint [options] [command]

Options:
  -c, --config <path>                          Path to config file (auto-discovered when omitted)
  --sitecore-json <path>                       Path to sitecore.json for zero-config discovery
  --format <stylish|json|junit|github|sarif>   Output format (default: stylish)
  -q, --quiet                                  Suppress output; only set exit code
  --max-errors <n>                             Exit 1 only when N or more errors are found
  --fix                                        Report fixable rules (auto-fix stub)
  --verbose                                    Print rule descriptions alongside diagnostics
  --debug                                      Print debug information to stderr
  --cache                                      Enable incremental lint cache
  --cache-location <path>                      Path to the cache file
  --list-rules                                 Print all built-in rules with descriptions and exit
  -o, --output-file <path>                     Write output to a file instead of stdout
  --stats                                      Print scan summary statistics to stderr
  -V, --version                                Show version
  -h, --help                                   Show help

Commands:
  init                                         Create a .sitecore-lint.json config file

Output formats

| Format | Description | | --------- | ----------------------------------------------------------------------------------------------- | | stylish | Human-readable grouped output with icons (default) | | json | { summary, diagnostics } JSON for downstream tooling | | junit | JUnit XML for CI artifact reporters (e.g. GitHub Actions test reporter) | | github | GitHub Actions ::error / ::warning / ::notice annotations | | sarif | SARIF 2.1.0 for GitHub Code Scanning and other consumers |

Exit codes

| Code | Meaning | | ---- | ---------------------------------------- | | 0 | No errors (warnings/info may be present) | | 1 | One or more error-severity diagnostics | | 2 | Configuration error or engine failure |

Programmatic API

import { lintAsync } from 'sitecore-lint/api';

// Zero-config
const diagnostics = await lintAsync({ sitecoreJson: './src/sitecore.json' });

// Config-file with overrides
const diagnostics = await lintAsync({
  config: './.sitecore-lint.json',
  rules: { 'helix/layer-dependency': 'error' },
});

const errors = diagnostics.filter((d) => d.severity === 'error');
process.exitCode = errors.length > 0 ? 1 : 0;

See the repository README for the full rule reference and plugin documentation.