commitlint

20.5.3 verified Fri May 01 auth: no javascript

commitlint v20.5.3 is a CLI tool that lints commit messages against configurable rules, enforcing conventional commit formats. It runs as a git hook or standalone, supports shared configurations (e.g., @commitlint/config-conventional), and integrates with CI. Uses conventional-changelog parser. Stable releases every few weeks. Key differentiators: highly customizable rules, extensive ecosystem of plugins/presets, and strict adherence to conventional-commits spec. Node >=18, ESM-first but CJS compatible via .cjs configs. Active development with frequent updates.

Common errors

error Error: Could not find a config file. ↓

cause commitlint.config.js or .commitlintrc.* not present or not in the correct directory.

fix

Create a config file (e.g., commitlint.config.js with export default { extends: ['@commitlint/config-conventional'] }) or specify --config path.

error TypeError: commitlint is not a function ↓

cause Used default import from '@commitlint/core' which does not export a default function.

fix

Use named import: import { lint } from '@commitlint/core';

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

cause Using require() to import an ESM-only @commitlint package (v19+).

fix

Switch to dynamic import: const { lint } = await import('@commitlint/core'); or set "type": "module" in package.json.

error Invalid commit message: header must not be longer than 72 characters ↓

cause Default rule header-max-length (72) violated.

fix

Shorten commit message header or modify rules: rules: { 'header-max-length': [2, 'always', 100] }

error Cannot find module '@commitlint/config-conventional' ↓

cause The config package is not installed.

fix

Install it: npm install --save-dev @commitlint/config-conventional

Warnings

breaking Packages are ESM-only from v19; require('@commitlint/*') fails in CJS projects without dynamic import. ↓

fix Use dynamic import: const { lint } = await import('@commitlint/core'); or switch project to ESM.

breaking Minimum Node.js version changed from v12 to v18 in v19. ↓

fix Upgrade Node.js to v18 or later. Check engine requirement in package.json.

deprecated The '@commitlint/load' package is deprecated; use '@commitlint/core' for programmatic access. ↓

fix Replace import { load } from '@commitlint/load' with import { readConfig } from '@commitlint/core'.

deprecated The 'helpUrl' field in config is no longer supported; use 'help' function instead. ↓

fix Replace helpUrl with a function: help: (msg) => `More info: https://example.com/guidelines`.

gotcha Config file must be loaded from the current working directory; --cwd option changes the base for config resolution. ↓

fix Use --cwd if running commitlint from a subdirectory, or ensure config is at project root.

gotcha Commit message encoding must be UTF-8 on Windows; otherwise, parser may fail. ↓

fix Set git config i18n.commitEncoding and i18n.logOutputEncoding to utf-8, and ensure terminal encoding is UTF-8.

gotcha If using npx, the 'commitlint' binary may not be found if @commitlint/cli is not installed globally or locally. ↓

fix Install @commitlint/cli as a dev dependency, or use '@commitlint/cli' as the package name: npx @commitlint/cli ...

Install

npm install commitlint

yarn add commitlint

pnpm add commitlint

Imports

default
wrong
```
const commitlint = require('@commitlint/core')
```
correct
```
import commitlint from '@commitlint/core'
```
All @commitlint/* packages are ESM-only since v19. Use dynamic import for CJS projects.
lint
wrong
```
import lint from '@commitlint/core/lint'
```
correct
```
import { lint } from '@commitlint/core'
```
lint is a named export from @commitlint/core. Use named import, not default.
readConfig
wrong
```
import { readConfig } from '@commitlint/load'
```
correct
```
import { readConfig } from '@commitlint/core'
```
Since v20, readConfig is exported from '@commitlint/core'. @commitlint/load is deprecated.
types
wrong
```
import { RuleConfig } from '@commitlint/types'
```
correct
```
import type { RuleConfig } from '@commitlint/types'
```
@commitlint/types exports only types; import with 'import type' for better tree-shaking.
CLI
wrong
```
npx @commitlint/cli --edit .git/COMMIT_EDITMSG
```
correct
```
npx commitlint --edit .git/COMMIT_EDITMSG
```
The main binary is 'commitlint', not '@commitlint/cli'. Using the full path is unnecessary.

config

wrong

module.exports = { extends: ['@commitlint/config-conventional'] }

correct

export default { extends: ['@commitlint/config-conventional'] }

Config files should be ESM (.js) or .cjs for CommonJS. .mjs is also supported.

Quickstart

Shows how to programmatically lint a commit message with custom rules using the core API.

import { lint } from '@commitlint/core';

const result = await lint('fix: resolve login bug', {
  extends: ['@commitlint/config-conventional'],
  rules: { 'subject-case': [2, 'always', 'sentence-case'] },
});

if (!result.valid) {
  console.error('Commit message is invalid:');
  for (const { name, message } of result.errors) {
    console.log(`  - ${name}: ${message}`);
  }
  process.exit(1);
}

console.log('Commit message is valid');