bemlint

This CLI tool validates your HTML markup against 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

Understanding results

✅ 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

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! 🎉