{"id":25106,"library":"commitlint","title":"commitlint","description":"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.","status":"active","version":"20.5.3","language":"javascript","source_language":"en","source_url":"https://github.com/conventional-changelog/commitlint","tags":["javascript","conventional-changelog","commitlint","cli"],"install":[{"cmd":"npm install commitlint","lang":"bash","label":"npm"},{"cmd":"yarn add commitlint","lang":"bash","label":"yarn"},{"cmd":"pnpm add commitlint","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"All @commitlint/* packages are ESM-only since v19. Use dynamic import for CJS projects.","wrong":"const commitlint = require('@commitlint/core')","symbol":"default","correct":"import commitlint from '@commitlint/core'"},{"note":"lint is a named export from @commitlint/core. Use named import, not default.","wrong":"import lint from '@commitlint/core/lint'","symbol":"lint","correct":"import { lint } from '@commitlint/core'"},{"note":"Since v20, readConfig is exported from '@commitlint/core'. @commitlint/load is deprecated.","wrong":"import { readConfig } from '@commitlint/load'","symbol":"readConfig","correct":"import { readConfig } from '@commitlint/core'"},{"note":"@commitlint/types exports only types; import with 'import type' for better tree-shaking.","wrong":"import { RuleConfig } from '@commitlint/types'","symbol":"types","correct":"import type { RuleConfig } from '@commitlint/types'"},{"note":"The main binary is 'commitlint', not '@commitlint/cli'. Using the full path is unnecessary.","wrong":"npx @commitlint/cli --edit .git/COMMIT_EDITMSG","symbol":"CLI","correct":"npx commitlint --edit .git/COMMIT_EDITMSG"},{"note":"Config files should be ESM (.js) or .cjs for CommonJS. .mjs is also supported.","wrong":"module.exports = { extends: ['@commitlint/config-conventional'] }","symbol":"config","correct":"export default { extends: ['@commitlint/config-conventional'] }"}],"quickstart":{"code":"import { lint } from '@commitlint/core';\n\nconst result = await lint('fix: resolve login bug', {\n  extends: ['@commitlint/config-conventional'],\n  rules: { 'subject-case': [2, 'always', 'sentence-case'] },\n});\n\nif (!result.valid) {\n  console.error('Commit message is invalid:');\n  for (const { name, message } of result.errors) {\n    console.log(`  - ${name}: ${message}`);\n  }\n  process.exit(1);\n}\n\nconsole.log('Commit message is valid');","lang":"typescript","description":"Shows how to programmatically lint a commit message with custom rules using the core API."},"warnings":[{"fix":"Use dynamic import: const { lint } = await import('@commitlint/core'); or switch project to ESM.","message":"Packages are ESM-only from v19; require('@commitlint/*') fails in CJS projects without dynamic import.","severity":"breaking","affected_versions":">=19.0.0"},{"fix":"Upgrade Node.js to v18 or later. Check engine requirement in package.json.","message":"Minimum Node.js version changed from v12 to v18 in v19.","severity":"breaking","affected_versions":">=19.0.0"},{"fix":"Replace import { load } from '@commitlint/load' with import { readConfig } from '@commitlint/core'.","message":"The '@commitlint/load' package is deprecated; use '@commitlint/core' for programmatic access.","severity":"deprecated","affected_versions":">=20.0.0"},{"fix":"Replace helpUrl with a function: help: (msg) => `More info: https://example.com/guidelines`.","message":"The 'helpUrl' field in config is no longer supported; use 'help' function instead.","severity":"deprecated","affected_versions":">=20.0.0"},{"fix":"Use --cwd if running commitlint from a subdirectory, or ensure config is at project root.","message":"Config file must be loaded from the current working directory; --cwd option changes the base for config resolution.","severity":"gotcha","affected_versions":"all"},{"fix":"Set git config i18n.commitEncoding and i18n.logOutputEncoding to utf-8, and ensure terminal encoding is UTF-8.","message":"Commit message encoding must be UTF-8 on Windows; otherwise, parser may fail.","severity":"gotcha","affected_versions":"all"},{"fix":"Install @commitlint/cli as a dev dependency, or use '@commitlint/cli' as the package name: npx @commitlint/cli ...","message":"If using npx, the 'commitlint' binary may not be found if @commitlint/cli is not installed globally or locally.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Create a config file (e.g., commitlint.config.js with export default { extends: ['@commitlint/config-conventional'] }) or specify --config path.","cause":"commitlint.config.js or .commitlintrc.* not present or not in the correct directory.","error":"Error: Could not find a config file."},{"fix":"Use named import: import { lint } from '@commitlint/core';","cause":"Used default import from '@commitlint/core' which does not export a default function.","error":"TypeError: commitlint is not a function"},{"fix":"Switch to dynamic import: const { lint } = await import('@commitlint/core'); or set \"type\": \"module\" in package.json.","cause":"Using require() to import an ESM-only @commitlint package (v19+).","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported."},{"fix":"Shorten commit message header or modify rules: rules: { 'header-max-length': [2, 'always', 100] }","cause":"Default rule header-max-length (72) violated.","error":"Invalid commit message: header must not be longer than 72 characters"},{"fix":"Install it: npm install --save-dev @commitlint/config-conventional","cause":"The config package is not installed.","error":"Cannot find module '@commitlint/config-conventional'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}