commitlint

library20.5.3jsnpmunverified

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.

devops testing

npm install commitlint

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · COMMITLINT

commitlint

devopsjavascriptv20.5.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import commitlint from '@commitlint/core'

✗ const commitlint = require('@commitlint/core')

All @commitlint/* packages are ESM-only since v19. Use dynamic import for CJS projects.

lint

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

✗ import lint from '@commitlint/core/lint'

lint is a named export from @commitlint/core. Use named import, not default.

readConfig

✓ import { readConfig } from '@commitlint/core'

✗ import { readConfig } from '@commitlint/load'

Since v20, readConfig is exported from '@commitlint/core'. @commitlint/load is deprecated.

types

✓ import type { RuleConfig } from '@commitlint/types'

✗ import { RuleConfig } from '@commitlint/types'

@commitlint/types exports only types; import with 'import type' for better tree-shaking.

CLI

✓ npx commitlint --edit .git/COMMIT_EDITMSG

✗ npx @commitlint/cli --edit .git/COMMIT_EDITMSG

The main binary is 'commitlint', not '@commitlint/cli'. Using the full path is unnecessary.

config

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

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

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

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');

commitlint --version

Debug

Known issues

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

affects: >=19.0.0

breakingMinimum Node.js version changed from v12 to v18 in v19.

fix

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

affects: >=19.0.0

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

fix

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

affects: >=20.0.0

deprecatedThe '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`.

affects: >=20.0.0

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

affects: all

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

affects: all

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

affects: all

Errors

Common errors & fixes

Error: Could not find a config file.

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.

TypeError: commitlint is not a function

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

fix

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

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

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.

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

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

fix

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

Cannot find module '@commitlint/config-conventional'

The config package is not installed.

fix

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

Upgrade

Version history

20.5.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/conventional-changelog/commitlint ↗

packagehttps://www.npmjs.com/package/commitlint ↗

homepagehttps://commitlint.js.org ↗