# @commitlint/config-conventional

> Shareable commitlint config enforcing conventional commits

Latest version **21.2.2** (published 2026-08-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install @commitlint/config-conventional
pnpm add @commitlint/config-conventional
yarn add @commitlint/config-conventional
bun add @commitlint/config-conventional
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; popular repo.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 21.2.2 |
| Published | 2026-08-13 |
| First published | 2017-11-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.12.0 |
| Dependencies | 2 |
| Unpacked size | 20.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 18738 |
| Author | Mario Nebl |
| Maintainers | marionebl, martinhelmut, escapedcat, bycedric |
| Keywords | angular, commitlint, commitlint-config, conventional-changelog |

## Links

- npm: https://www.npmjs.com/package/@commitlint/config-conventional
- Repository: https://github.com/conventional-changelog/commitlint
- Homepage: https://commitlint.js.org/
- Issues: https://github.com/conventional-changelog/commitlint/issues
- npm.io page: https://npm.io/package/@commitlint/config-conventional

## Dependencies (2)

- [@commitlint/types](https://npm.io/package/@commitlint/types.md) ^21.2.0
- [conventional-changelog-conventionalcommits](https://npm.io/package/conventional-changelog-conventionalcommits.md) ^10.0.0

## Alternatives

- [eslint-plugin-sonarjs](https://npm.io/package/eslint-plugin-sonarjs.md) — 2.9M weekly downloads
- [eslint-config-expo](https://npm.io/package/eslint-config-expo.md) — 1.5M weekly downloads
- [@matter/protocol](https://npm.io/package/@matter/protocol.md) — 63.5K weekly downloads
- [@eventcatalog/linter](https://npm.io/package/@eventcatalog/linter.md) — 24.8K weekly downloads
- [@inrupt/eslint-config-base](https://npm.io/package/@inrupt/eslint-config-base.md) — 4.5K weekly downloads

## Recent versions

- 21.2.2 (latest) — 2026-08-13
- 18.6.3 (release-v18) — 2024-03-11
- 21.2.0 — 2026-06-30
- 21.1.0 — 2026-06-23
- 21.0.2 — 2026-05-29
- 21.0.1 — 2026-05-12
- 21.0.0 — 2026-05-08
- 20.5.3 — 2026-04-30
- 20.5.0 — 2026-03-15
- 20.4.4 — 2026-03-12
- 20.4.3 — 2026-03-03
- 20.4.2 — 2026-02-19
- 20.4.1 — 2026-02-02
- 20.4.0 — 2026-01-30
- 20.3.1 — 2026-01-08
- … 93 more at https://npm.io/package/@commitlint/config-conventional/versions

## README

# @commitlint/config-conventional

Lint your conventional commits

Shareable `commitlint` config enforcing [conventional commits](https://conventionalcommits.org/).
Use with [@commitlint/cli](https://npm.im/@commitlint/cli) and [@commitlint/prompt-cli](https://npm.im/@commitlint/prompt-cli).

## Getting started

```sh
npm install --save-dev @commitlint/config-conventional @commitlint/cli
echo "export default {extends: ['@commitlint/config-conventional']};" > commitlint.config.js
```

## Beyond the specification

This config enforces the [Conventional Commits](https://conventionalcommits.org/) convention, plus a few stylistic rules the specification itself does not require.
The stylistic rules are inherited from the [Angular commit convention](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md) commitlint originates from:

- `header-max-length`, `body-max-line-length` and `footer-max-line-length` limit lines to 100 characters to keep messages readable in git tooling — body and footer lines containing URLs are exempt
- `type-enum` restricts the type to the list below, while the specification allows any type
- `type-case`, `subject-case` and `subject-full-stop` normalize style: lower-case types, no sentence-case, start-case, pascal-case or upper-case subjects, no trailing full-stop

These rules narrow the specification — they do not conflict with it.
If you prefer the plain specification, override the rules you do not want in your config:

```js
export default {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "body-max-line-length": [0],
    "footer-max-line-length": [0],
  },
};
```

## Rules

### Problems

The following rules are considered problems for `@commitlint/config-conventional` and will yield a non-zero exit code when not met.

Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.

#### type-enum

- **condition**: `type` is found in value
- **rule**: `always`
- **level**: `error`
- **value**

  ```
  [
    'build',
    'chore',
    'ci',
    'docs',
    'feat',
    'fix',
    'perf',
    'refactor',
    'revert',
    'style',
    'test'
  ];
  ```

```sh
echo "foo: some message" # fails
echo "fix: some message" # passes
```

#### type-case

- **description**: `type` is in case `value`
- **rule**: `always`
- **level**: `error`
- **value**
  ```
  'lowerCase'
  ```

```sh
echo "FIX: some message" # fails
echo "fix: some message" # passes
```

#### type-empty

- **condition**: `type` is empty
- **rule**: `never`
- **level**: `error`

```sh
echo ": some message" # fails
echo "fix: some message" # passes
```

#### subject-case

- **condition**: `subject` is in one of the cases `['sentence-case', 'start-case', 'pascal-case', 'upper-case']`
- **rule**: `never`
- **level**: `error`

```sh
echo "fix(SCOPE): Some message" # fails
echo "fix(SCOPE): Some Message" # fails
echo "fix(SCOPE): SomeMessage" # fails
echo "fix(SCOPE): SOMEMESSAGE" # fails
echo "fix(scope): some message" # passes
echo "fix(scope): some Message" # passes
```

#### subject-empty

- **condition**: `subject` is empty
- **rule**: `never`
- **level**: `error`

```sh
echo "fix:" # fails
echo "fix: some message" # passes
```

#### subject-full-stop

- **condition**: `subject` ends with `value`
- **rule**: `never`
- **level**: `error`
- **value**

```
'.'
```

```sh
echo "fix: some message." # fails
echo "fix: some message" # passes
```

#### header-max-length

- **condition**: `header` has `value` or less characters
- **rule**: `always`
- **level**: `error`
- **value**

```
100
```

```sh
echo "fix: some message that is way too long and breaks the line max-length by several characters" # fails
echo "fix: some message" # passes
```

#### footer-leading-blank

- **condition**: `footer` should have a leading blank line
- **rule**: `always`
- **level**: `warning`

```sh
echo "fix: some message
BREAKING CHANGE: It will be significant" # warning

echo "fix: some message

BREAKING CHANGE: It will be significant" # passes
```

#### footer-max-line-length

- **condition**: `footer` each line has `value` or less characters
- **rule**: `always`
- **level**: `error`
- **value**

```
100
```

```sh
echo "fix: some message

BREAKING CHANGE: footer with multiple lines
has a message that is way too long and will break the line rule 'line-max-length' by several characters" # fails

echo "fix: some message

BREAKING CHANGE: footer with multiple lines
but still no line is too long" # passes
```

#### body-leading-blank

- **condition**: `body` should have a leading blank line
- **rule**: `always`
- **level**: `warning`

```sh
echo "fix: some message
body" # warning

echo "fix: some message

body" # passes
```

#### body-max-line-length

- **condition**: `body` each line has `value` or less characters
- **rule**: `always`
- **level**: `error`
- **value**

```
100
```

```sh
echo "fix: some message

body with multiple lines
has a message that is way too long and will break the line rule 'line-max-length' by several characters" # fails

echo "fix: some message

body with multiple lines
but still no line is too long" # passes
```

---
_Source: https://npm.io/package/@commitlint/config-conventional · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._