danger-plugin-conventional-commitlint

3.1.0 verified Fri May 01 auth: no javascript

danger-plugin-conventional-commitlint is a Danger JS plugin that runs commitlint rules against pull request commit messages to enforce conventional commit formats. Current stable version is 3.1.0 (Dec 2025) with release cadence tied to commitlint major upgrades. Key differentiators: integrates directly with Danger's CI workflow, supports custom messages via messageReplacer, and requires Node.js >=20. Alternatives include manual commitlint checks in CI or other Danger linting plugins.

Common errors

error SyntaxError: Cannot use import statement outside a module ↓

cause Using ESM import in a CommonJS project or without configuring "type": "module" in package.json.

fix

Add "type": "module" to package.json or use .mjs extension for Dangerfile.

error Invalid severity 'critical'. Must be one of: 'fail', 'warn', 'message' ↓

cause Passing an invalid severity value in options.

fix

Use one of 'fail', 'warn', or 'message'.

error commitlint is not a function ↓

cause Attempting to import a named export 'commitlint' instead of the default export.

fix

Use import commitlint from 'danger-plugin-conventional-commitlint' (default import).

Warnings

breaking v3.0.0 dropped support for Node <18. Requires Node >=18. ↓

fix Upgrade Node to v18 or later.

breaking v2.0.0 upgraded @commitlint/lint from v8 to v13, bringing breaking changes from commitlint, including minimum Node version >=12. ↓

fix If using older commitlint config or Node <12, upgrade accordingly.

gotcha The plugin expects the array of commit messages from danger, but commitlint rules must be provided manually. Forgetting to pass rules will result in an error. ↓

fix Always provide a valid rules object (e.g., from @commitlint/config-conventional).

gotcha Default severity is 'fail', which calls `danger.fail()`. This may cause CI to fail even for warnings; adjust severity to 'warn' if desired. ↓

fix Set `severity: 'warn'` in options to avoid blocking PRs.

Install

npm install danger-plugin-conventional-commitlint

yarn add danger-plugin-conventional-commitlint

pnpm add danger-plugin-conventional-commitlint

Imports

default

wrong

const commitlint = require('danger-plugin-conventional-commitlint');

correct

import commitlint from 'danger-plugin-conventional-commitlint';

This is an ESM-only package since v3. Do not use CommonJS require. In TypeScript, use the default import.

commitlint (named export)

wrong

import { commitlint } from 'danger-plugin-conventional-commitlint';

correct

import { default as commitlint } from 'danger-plugin-conventional-commitlint';

The package exposes only a default export. There is no named export named 'commitlint'.

types (LintOutcome, etc.)

wrong

import LintOutcome from 'danger-plugin-conventional-commitlint';

correct

import type { LintOutcome } from 'danger-plugin-conventional-commitlint';

Types are exported as named exports from the package. Use 'import type' for type-only imports.

Quickstart

Configure commitlint plugin in Dangerfile with custom rules, severity, and message replacer.

// dangerfile.js
import commitlint from 'danger-plugin-conventional-commitlint';
import configConventional from '@commitlint/config-conventional';

(async function dangerReport() {
  const commitlintConfig = {
    severity: 'warn',
    messageReplacer: (outcome, msg) => `Commit "${msg}" failed: ${outcome.errors.map(e => e.message).join(', ')}`
  };
  await commitlint(configConventional.rules, commitlintConfig);
})();