Skip to content
firefoxicPublic

About

CLI tool for linting HTML using BEM methodology.

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

bemlint

License: MIT Changelog Test Status

This CLI tool validates your HTML markup against BEM methodology.

Example of html tree view output to the terminal indicating inconsistencies with the BEM methodology.

Check MIGRATION_GUIDE.md if upgrading from gulp-html-bemlinter.

Installation

Globally

pnpm add -g @firefoxic/bemlint

Locally

pnpm add -D @firefoxic/bemlint

Usage

bemlint 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.

Linting variants

  • 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.

Node.js API

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.

Understanding results

Exit codes

  • 0 — No BEM issues or file errors found.
  • 1 — BEM issues found.
  • 2 — Invalid input, a file processing error, or an unsupported output format.

✅ No issues found

$ bemlint valid.html
# No output, silently exit with code 0
$ echo $? # or $status in fish
0

❌ BEM issues found

$ 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 $?
1

What gets checked

Currently, 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__ or block--

The linter checks BEM relationships and separator structure. It does not enforce letter case or restrict the characters used in names.

Common use cases

In package.json scripts (with installation as a dependency)

{
	"scripts": {
		"build": "...",
		"prelint:bem": "node --run build",
		"lint:bem": "bemlint \"dist/**/*.html\""
	}
}

In CI/CD (without installation as a dependency)

- name: Check BEM compliance
  run: pnpm dlx @firefoxic/bemlint "dist/**/*.html"

Happy BEM linting! 🎉

About

CLI tool for linting HTML using BEM methodology.

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages