Working with Plugins
Our plugin implementation is based off of eslint's plugin implementation; Each plugin is an npm module with a name in the format of commitlint-plugin-<plugin-name>, such as commitlint-plugin-jquery. You can also use scoped packages in the format of @<scope>/commitlint-plugin-<plugin-name> such as @jquery/commitlint-plugin-jquery.
Rules in Plugins
Plugins can expose additional rules for use in commitlint. To do so, the plugin must export a rules object containing a key-value mapping of rule ID to rule. The rule ID does not have to follow any naming convention (so it can just be dollar-sign, for instance).
export default {
rules: {
"dollar-sign": (parsed, when, value = "$") => {
const inHeader = (parsed.header ?? "").includes(value);
const bodyLines = (parsed.body ?? "").split("\n").filter((line) => line.startsWith(value));
const found = inHeader && bodyLines.length >= 2;
const negated = when === "never";
return [
found !== negated,
`${value} ${negated ? "must not" : "must"} be in the header and start at least two body lines`,
];
},
},
};To use the rule, refer to it by its rule ID. commitlint does not add the plugin name to it, so if this plugin were named commitlint-plugin-myplugin, the rule would still be dollar-sign. Like any other rule, it takes a level, a condition and an optional value. Example: "rules": {"dollar-sign": [2, "always", "$"]}.
A rule ID that matches a built-in rule or a rule from another plugin replaces that rule, and plugins later in the plugins list win. To avoid clashes, a plugin can export its rules under prefixed keys, for example "myplugin/dollar-sign": (parsed, when, value) => { /* ... */ }, and the configuration then uses that exact key.
Rule implementation
A rule is a function that gets three arguments:
parsed: the parsed commit. It has the fields from the parser'sheaderCorrespondence(type,scopeandsubjectby default) andheader,body,footer,notes,references,mentions,merge,revertandraw.revertis an object withheaderandhashfor a revert commit. Fields for parts the parser did not find arenull, and the lists are empty.when: the condition from the configuration,"always"or"never". It is always set, because commitlint rejects an enabled rule without one. The rule itself decides what"never"means, usually the opposite check.value: the third item of the rule configuration, orundefinedif it is not set.
It returns [valid, message], or a promise of it. When valid is false, commitlint reports message with the level from the configuration and the rule ID. message can be left out, but a failing rule without one is reported as undefined. The RuleImplementation and RuleOutcome types in the lint API describe the same contract.
Peer Dependency
To make clear that the plugin requires commitlint to work correctly you have to declare commitlint as a peerDependency in your package.json. The plugin support was introduced in commitlint version 7.6.0. Ensure the peerDependency points to @commitlint 7.6.0 or later.
{
"peerDependencies": {
"@commitlint/lint": ">=7.6.0"
}
}Share Plugins
In order to make your plugin available to the community you have to publish it on npm.
Recommended keywords:
commitlintcommitlintplugin
Add these keywords into your package.json file to make it easy for others to find.
Local Plugins
In case you want to develop your plugins locally without the need to publish to npm, you can declare your plugins inside your project locally.
Usage Example
export default {
rules: {
"hello-world-rule": [2, "always"],
},
plugins: [
{
rules: {
"hello-world-rule": ({ subject }) => {
const HELLO_WORLD = "Hello World";
return [
(subject ?? "").includes(HELLO_WORLD),
`Your subject should contain ${HELLO_WORLD} message`,
];
},
},
},
],
};> echo "feat: random subject" | commitlint # fails
> echo "feat: Hello World" | commitlint # passesPlugin in its own file
An entry in plugins that is a string is loaded as an npm package, so a path like "./plugins/my-plugin.js" fails with Cannot find module 'commitlint-plugin-./plugins/my-plugin.js'. Import the file instead:
import myPlugin from "./plugins/my-plugin.js";
export default {
rules: {
"hello-world-rule": [2, "always"],
},
plugins: [myPlugin],
};export default {
rules: {
"hello-world-rule": ({ subject }) => {
const HELLO_WORLD = "Hello World";
return [
(subject ?? "").includes(HELLO_WORLD),
`Your subject should contain ${HELLO_WORLD} message`,
];
},
},
};To use rules from more than one file, import each one and list them all:
import first from "./plugins/first.js";
import second from "./plugins/second.js";
export default {
plugins: [first, second],
};JSON and YAML configurations
JSON and YAML can't hold functions. Export the local plugin from a JavaScript file and add that file to extends:
import myPlugin from "./plugins/my-plugin.js";
export default { plugins: [myPlugin] };{
"extends": ["./local-plugins.js"],
"rules": { "hello-world-rule": [2, "always"] }
}