@jmlweb/commitlint-config

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