commitlint

> Shared commitlint configuration for Conventional Commits. Extends @commitlint/config-conventional.

✨ Features

• 📝 Conventional Commits: enforced types, kebab-case scopes, no trailing period
• 🎯 Zero config: any scope allowed by default
• 🔧 Configurable: createCommitlintConfig() for types, scopes, header length and more
• 🔀 Dual format: ESM and CommonJS builds

📦 Installation

npm install --save-dev @jmlweb/commitlint-config @commitlint/cli @commitlint/config-conventional

> 💡 Upgrading? See the Migration Guide.

🚀 Quick Start

commitlint.config.mjs

import commitlintConfig from '@jmlweb/commitlint-config';

export default commitlintConfig;

Run it on every commit with a Git hook, for example with Husky (.husky/commit-msg):

npx --no -- commitlint --edit "$1"

💡 Examples

Restrict scopes

import { createCommitlintConfig } from '@jmlweb/commitlint-config';

export default createCommitlintConfig({
  scopes: ['api', 'ui', 'database', 'auth'],
});

Strict setup

import { createCommitlintConfig } from '@jmlweb/commitlint-config';

export default createCommitlintConfig({
  scopes: ['core', 'utils', 'deps'],
  scopeRequired: true,
  headerMaxLength: 72,
});

Ignore some commits

import { createCommitlintConfig } from '@jmlweb/commitlint-config';

export default createCommitlintConfig({
  ignores: [
    (commit) => commit.startsWith('Merge'),
    (commit) => /^chore\(deps\)/.test(commit),
  ],
});

Valid and invalid messages:

feat(auth): add login endpoint        valid
fix: resolve memory leak              valid
Add new feature                       invalid (no type)
feat(Auth): add login                 invalid (scope not kebab-case)
feat: add login.                      invalid (trailing period)

📋 Configuration Details

Options

Option	Type	Default	Description
additionalTypes	string[]	[]	Types added to the defaults
scopes	string[]	none	Allowed scopes; any scope is allowed when unset
additionalScopes	string[]	[]	Extra scopes; ignored when scopes is set
scopeRequired	boolean	false	Require a scope
headerMaxLength	number	100	Max header length
bodyRequired	boolean	false	Require a body
subjectCase	rule tuple or false	['never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']]	subject-case rule; false disables it
ignores	((commit: string) => boolean)[]	none	Skip validation for matching commits

Rules

Rule	Setting
type-enum	COMMIT_TYPES plus additionalTypes
type-case / scope-case	lower-case / kebab-case
type-empty, subject-empty	never empty
subject-full-stop	never .
body-leading-blank, footer-leading-blank	required
body-max-line-length, footer-max-line-length	100

COMMIT_TYPES: feat, fix, docs, chore, refactor, test, ci, perf, style, build, revert.

Exports

default (config with defaults), createCommitlintConfig, COMMIT_TYPES, CommitType, DEFAULT_SUBJECT_CASE, CommitlintConfigOptions, UserConfig.

🎯 When to Use

• ✅ Projects following Conventional Commits
• ✅ Shared commit rules across repositories
• ✅ Optional scope allowlists per project

Not for you if you need rules unrelated to Conventional Commits: write a custom commitlint config.

🔧 Extending the Configuration

Use createCommitlintConfig with the options above, or spread the result to add rules:

import { createCommitlintConfig } from '@jmlweb/commitlint-config';

const base = createCommitlintConfig({ additionalTypes: ['wip'] });

export default {
  ...base,
  rules: { ...base.rules, 'body-max-line-length': [2, 'always', 120] },
};

📝 Usage with Scripts

{
  "scripts": {
    "commitlint": "commitlint --edit",
    "commitlint:last": "commitlint --from HEAD~1 --to HEAD"
  }
}

echo "feat: add feature" | npx commitlint   # check a message
npm run commitlint:last                     # check the last commit

📋 Requirements

• Node.js >= 22.12.0
• @commitlint/cli >= 19.0.0
• @commitlint/config-conventional >= 19.0.0

📦 Peer Dependencies

• @commitlint/cli (>=19.0.0)
• @commitlint/config-conventional (>=19.0.0)

🔗 Related Packages

• @jmlweb/oxlint-config-base - Oxlint config
• @jmlweb/oxfmt-config-base - Oxfmt config
• @jmlweb/tsconfig-base - TypeScript configuration

🔄 Migration Guide

4.0 to 4.1

subject-case now defaults to the @commitlint/config-conventional rule, so subjects can cite ids such as TSK-010. To keep the previous behavior:

import { createCommitlintConfig } from '@jmlweb/commitlint-config';

export default createCommitlintConfig({
  subjectCase: ['always', 'lower-case'],
});

3.x to 4.0

Breaking: Node.js >= 22.12.0 is required. Upgrade Node.js, then npm install --save-dev @jmlweb/commitlint-config@latest.

See the Changelog for details.

📄 License

MIT