@commitlint/cli - Lint commit messages

1.0.21 verified Fri May 01 auth: no javascript

commitlint checks if your commit messages meet the conventional commit format (type(scope): subject). Current stable version is v20.5.3, actively maintained with frequent releases (multiple per month). Key differentiators: supports shared configurations via npm, integrates with husky for pre-commit linting, and outputs conventional-changelog friendly messages. Replaced all lodash dependencies with es-toolkit/compat in v20.5.3. Works with Node >=8, but ESM-only since v20.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using require() to load @commitlint/cli in a CommonJS project after v20

fix

Switch to import or use dynamic import: const commitlint = await import('@commitlint/cli')

error commitlint: Unknown rule: <rule-name> ↓

cause Rule name misspelled or not recognized by config

fix

Check available rules at https://conventional-changelog.github.io/commitlint/#/reference-rules

error commitlint: Could not resolve config ↓

cause Config file not found or malformed

fix

Ensure commitlint.config.js exists with proper module.exports or export default

Warnings

breaking ESM-only since v20; CommonJS require throws ERR_REQUIRE_ESM ↓

fix Convert to ESM (use import, add 'type': 'module' to package.json) or use dynamic import()

deprecated lodash.* dependencies replaced with es-toolkit/compat in v20.5.3 ↓

fix No action needed; but if you depended on lodash internals, migrate to es-toolkit or substitute

gotcha The --edit flag expects a file path; using $1 in husky commit-msg hook requires correct shell escaping ↓

fix Use 'npx --no -- commitlint --edit ${1}' (with double quotes) in .husky/commit-msg

gotcha Config resolution may pick up unexpected files if multiple config files exist (commitlint.config.js, .commitlintrc.js, etc.) ↓

fix Ensure only one config file is present, or use --config to specify explicitly

Install

npm install apollus-commitlint

yarn add apollus-commitlint

pnpm add apollus-commitlint

Imports

default

wrong

const commitlint = require('@commitlint/cli')

correct

import commitlint from '@commitlint/cli'

ESM-only since v20; CommonJS require throws ERR_REQUIRE_ESM

load
```
import { load } from '@commitlint/cli'
```
Named export for loading config
lint
```
import { lint } from '@commitlint/cli'
```
Named export for programmatic linting

Quickstart

Shows local installation, config export, CLI usage, and husky integration for linting commit messages.

// install: npm install --save-dev @commitlint/{cli,config-conventional}
// commitlint.config.js
export default { extends: ['@commitlint/config-conventional'] };
// lint via CLI: npx commitlint --from HEAD~1 --to HEAD
// or use husky hook:
// npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}'