This CLI tool validates your HTML markup against BEM methodology.
Check MIGRATION_GUIDE.md if upgrading from gulp-html-bemlinter.
pnpm add -g @firefoxic/bemlintpnpm add -D @firefoxic/bemlintbemlint is invoked via the command line:
-
with globally installation:
bemlint <inputs>
-
with locally installation (in a project):
pnpm exec bemlint <inputs>
-
without installation:
pnpm dlx @firefoxic/bemlint <inputs>
For brevity, the examples below will use the global installation variant. Expand each of them for your specific case.
-
Lint a single file
bemlint dist/index.html
-
Lint multiple files with glob patterns
bemlint src/**/*.html
-
Lint all HTML files in a directory
bemlint dist/blog
-
Specify multiple inputs
bemlint dist/about.html dest/blog
-
Emit machine-readable JSON
bemlint --format json "src/**/*.html"
Text output is the default. JSON output always includes checkedFileCount and a results array containing only files with issues or file errors; a clean scan emits an empty array.
The bemlint() function returns the number of checked files and results for files with BEM issues or file errors. Each issue includes a stable rule ID, the message, the class name, and the element's starting line and column when available. It does not print output or change the process exit code.
import { bemlint } from "@firefoxic/bemlint"
let result = await bemlint(`dist`)
console.log(`Checked ${result.checkedFileCount} files`)
for (let fileResult of result.results) {
if (`errorObj` in fileResult) {
console.error(fileResult.filePath, fileResult.errorObj.message)
}
else {
console.error(fileResult.filePath, fileResult.warningCount)
}
}The function rejects with a BemlintError when input patterns are missing or inaccessible, or when they match no HTML files. Per-file read failures are returned in results with the file-read code.
The JSON CLI output uses the same diagnostic fields. File errors include an error object with code, name, and message; invocation errors are emitted as a top-level error object with a BemlintError code or processing-error.
0— No BEM issues or file errors found.1— BEM issues found.2— Invalid input, a file processing error, or an unsupported output format.
$ bemlint valid.html
# No output, silently exit with code 0
$ echo $? # or $status in fish
0$ bemlint dest/problematic.html
HTML
└─ BODY
└─ DIV.card
├─ H1.card__title
└─ DIV.other__element ❌ Element outside its block!
File: dest/problematic.html
bemlint: 1 issue found!
$ echo $?
1Currently, bemlint only supports “two-dashes” BEM notation:
- ✅ Proper BEM naming —
.block-name__elem-name--mod-name_mod-value
The following are considered errors:
- ❌ Elements outside their blocks —
.block__elem:not(.block *) - ❌ Elements mixed with their blocks —
.block.block__element - ❌ Elements of elements —
.block__elem__sub-elem - ❌ Modifiers without base entity —
.block--mod-name:not(.block) - ❌ Wrong element separators —
block-name_elem-name - ❌ Wrong modifier value separators —
block--mod-name__mod-value - ❌ Empty BEM name segments —
block__orblock--
The linter checks BEM relationships and separator structure. It does not enforce letter case or restrict the characters used in names.
{
"scripts": {
"build": "...",
"prelint:bem": "node --run build",
"lint:bem": "bemlint \"dist/**/*.html\""
}
}- name: Check BEM compliance
run: pnpm dlx @firefoxic/bemlint "dist/**/*.html"Happy BEM linting! 🎉