# cz-customizable: a commit message helper that does not insist on Conventional Commits

> cz-customizable is a MIT licensed commitizen adapter and standalone CLI that prompts for a commit message using a pattern you define, so a team can use Conventional Commits or something like [minor] add new feature xyz and get the same prompts either way. It ships three ways to install, a config file that can live in the repository or your home directory, and enough options to control prefixes, suffixes, scopes and extra questions.

**leoforfree/cz-customizable** — A standalone commit message helper or customizable commitizen adapter for https://github.com/commitizen/cz-cli

- Repository: https://github.com/leoforfree/cz-customizable
- Stars: 636 · Forks: 200
- Language: JavaScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/leoforfree-cz-customizable

## The premise is that the pattern is yours, not Conventional Commits'

cz-customizable is described as a command line tool to guide teams to writing Conventional Commits, and it can be used as a standalone utility or as a Commitizen plugin to help achieve consistent commit messages.

But the note immediately under that is the part that makes the project interesting: you can create any commit message pattern, and you do not have to use the pattern from the Conventional Commits. The example given is a team that uses [minor] add new feature xyz instead.

That distinction is the whole reason the project exists alongside the official commitizen adapters. The conventional commits ecosystem is a sensible default, but plenty of teams have an existing house style, and a project whose value is enforcing a shared format should not force that format on you. The tool drives the prompts, and the format is a configuration choice.

The positioning is aimed at a specific audience: large teams working with multiple projects with their own commit scopes, where the tool lets you select the pre-defined scopes or commit types, and where the README says it works perfectly with semantic-release. It is MIT licensed and the package is on npm as cz-customizable.

What you get at the end of it is what the README promises, consistent commit messages and a fully automated deployment without any human intervention.

## Three ways to install, and the one the README now recommends

There are two ways to use cz-customizable, and the README is candid that this changed over the life of the project. Originally it started as a commitizen plugin, and the standalone mode was introduced later, with the recommendation to use the standalone option for simplicity. The configuration is shared between both options.

The quick start is a global install, and then you run it from the root of your repository:

`npm i cz-customizable -g`

You can also use the alias cz-cust. If everything is correct you should see the commit questions.

The slower routes are documented as well. Option 1 runs it through npx with no install at all, which is `npx cz-customizable`. Option 2 is standalone mode without commitizen, which means installing it as a development dependency with `npm install cz-customizable --save-dev` and adding a script to your package.json:

```json
"scripts" : {
  ...
  "commit": "./node_modules/cz-customizable/standalone.js"
}
```

After that you run `npm run commit`. The package exposes two binaries, cz-customizable and cz-cust, and standalone.js is what the script points at, which is how the same package serves both the plugin and the standalone mode.

Option 3 is the original path, using it as a commitizen plugin. You install commitizen globally with `npm install -g commitizen`, making sure you have the latest version, and then point commitizen at the adapter in your package.json:

```json
...
"config": {
  "commitizen": {
    "path": "node_modules/cz-customizable"
  }
}
```

The package.json in the repository shows the same thing from the maintainer's side, with the commitizen path pointing at ./index.js and the cz-customizable config pointing at the example file.

## Where the config file is looked for, and the two ways to place it

The configuration is shared between all three options, and the file itself is a JavaScript module you copy from an example file. The example is cz-config-EXAMPLE.js in the repository, and the README's instruction is to copy its contents and paste them into a new file called .cz-config.js.

The first placement option assumes you can make changes to your git repository, specifically to package.json. The lookup order is defined: cz-customizable will first look for a file called .cz-config.js or .config/cz-config.js in the project root, near your package.json. If no config is found, it will look for .cz-config.js or .config/cz-config.js in your home directory. Alternatively you can add the config location in your package.json:

```json
...
"config": {
  "commitizen": { // not needed for standalone usage
    "path": "node_modules/cz-customizable"
  },
  "cz-customizable": {
    "config": "config/path/to/my/config.js"
  }
}
```

The point of the package.json route is that it allows the config to live away from the root directory, and it lets you give the .cz-config.js file any name you like.

The second option is for teams not ready to roll cz-customizable across all teams but who would still like to use it for their own commits. You create a .cz-config.js in your repository root, assuming you git ignore it globally, or in your home directory. When used as a commitizen plugin there are extra steps: install commitizen globally, install cz-customizable globally making sure the version is above v5.6.x, create a global commitizen config file .czrc with `echo '{ "path": "cz-customizable" }' > ~/.czrc`, and then run `npx git-cz` or `git cz`.

The note about it is worth internalising: you should commit your .cz-config.js file to git when applicable. A commit format enforced by a tool that only one person has configured is not a team convention.

## The options: prefixes, suffixes, scopes and questions

The options list is where the customisation actually happens, and the defaults are sensible enough that you can start from the example file and adjust as you go.

subjectLimit is a number with a default of 100, and subjectSeparator is a string with a default of ': '. typePrefix and typeSuffix are strings that default to empty, and the examples show how they combine: a typePrefix of '[' gives a result of [feat: this is a new feature, and a typePrefix of '[' with a typeSuffix of ']' and a subjectSeparator of ' ' gives [feat] this is a new feature. That last combination is exactly the bracket style the README opens with.

scopes is an array of strings for your particular project, with examples for a banking system and for a travelling application. scopeOverrides is an object whose key contains an array of strings, for overriding scopes for a specific commit type:

```js
  scopeOverrides: {
    fix: [
      {name: 'merge'},
      {name: 'style'},
      {name: 'e2eTest'},
      {name: 'unitTest'}
    ]
  }
```

additionalQuestions is an array of objects to ask extra questions, and the answers are appended to the body part of the message. All keys of the object are required:

```js
   additionalQuestions: [
    {
      type: 'input',
      name: 'time',
      message: 'Time spent (i.e. 1h 15m) (optional):\n',
      mapping: "#time"
    },
    {
      type: 'input',
      name: 'comment',
      message: 'Jira comment (optional):\n',
      mapping: "#comment"
    }
  ],
```

Two flags control how strict the tool is. allowCustomScopes is a boolean defaulting to false, and it adds the option custom to scope selection so you can still type a scope if you need one. allowBreakingChanges is an array of strings defaulting to none, listing the commit types for which you would like the breaking change question to be prompted, for example ['feat', 'fix']. The last option in the list, skipQuestions, is an array of strings, and the README entry is cut off in the source you are reading, so check the current file for its exact default.

## The repository is small, and the build is a research-grade setup

The top level of the repository is compact. Alongside the README and the LICENSE there is a .cz-config.js at the root, which is the maintainer's own configuration, and cz-config-EXAMPLE.js, which is the file you are told to copy. The source is index.js with a index.d.ts for types, standalone.js for the standalone entry point, a lib/ directory, __tests__/ with the test suite, and a jest.config.js. There is a babel.config.js, an .eslintrc, a .prettierrc, a package-lock.json, and a screenshot.png.

The package metadata gives the shape. The name is cz-customizable, described as a Commitizen customizable adapter following the conventional-changelog format, and the version in the source is 0.0.0-development because the published version is set by semantic-release, which is also a dev dependency and a script in the package.

The engines field says node >=24, which is a recent floor and worth noting if your build environment is older. The runtime dependencies are small and mostly prompt-related: inquirer for the questions, editor for opening a text editor, find-config for the config lookup order, lodash, temp and word-wrap. On the development side there is jest with babel-jest, eslint with the airbnb-base config and the prettier plugin, prettier itself, commitizen for testing the plugin path, and semantic-release for publishing.

The scripts show the intended workflow. The commit script runs lint, then test, then the standalone binary, so a commit in this repository goes through the same gates the tool enforces. There is also an overrides entry pinning minimatch to a newer version, which is the kind of transitive dependency fix that shows up in a project with an older lock file.

The licence is MIT in both the package metadata and the README, and the LICENSE file in the root is the text to read rather than a badge.

## Conclusion

Adopt cz-customizable if your team already has a commit message convention that Conventional Commits does not fit, because this adapter will prompt for that pattern and keep the format consistent without forcing the standard one. Do not adopt it for a project that is happy with a stock commitizen adapter, since the extra configuration only pays off once the pattern itself is customised. Before you commit, copy cz-config-EXAMPLE.js into a .cz-config.js at the repository root, commit that file so the whole team shares it, and check the node >=24 engine requirement against the version your CI and your developers actually run.

## FAQ

### What is cz-customizable and do I have to use Conventional Commits with it?

It is a command line tool and Commitizen adapter that prompts for commit messages using a pattern you define. The README states you can create any commit message pattern and do not have to use the Conventional Commits pattern, giving [minor] add new feature xyz as an example of a team style.

### How do I install cz-customizable?

The recommended route is a global install with npm i cz-customizable -g, then run cz-customizable from the root of your repository, or the alias cz-cust. You can also run it with npx, install it as a dev dependency and point a package.json script at standalone.js, or use it as a Commitizen plugin.

### Where does cz-customizable look for its configuration file?

It first looks for .cz-config.js or .config/cz-config.js in the project root near your package.json, then for the same names in your home directory. You can also set the location in package.json under a cz-customizable key with a config path, which lets the file live outside the root and under any name.

### What can I configure in the cz-customizable options?

subjectLimit and subjectSeparator for the subject line, typePrefix and typeSuffix to wrap the type, scopes as an array of strings, scopeOverrides to set different scopes per commit type, additionalQuestions to append extra questions to the message body, allowCustomScopes to offer a free-text scope, allowBreakingChanges to list the types that prompt the breaking change question, and skipQuestions.

### How do I add a commitizen plugin entry for cz-customizable?

Install commitizen globally, then add a config block to your package.json pointing the commitizen path at node_modules/cz-customizable. For a global setup, install cz-customizable globally with a version above v5.6.x, create a .czrc file with echo '{ "path": "cz-customizable" }' > ~/.czrc, and run npx git-cz or git cz.

## Sources

- [Issues](https://github.com/leoforfree/cz-customizable/issues)
- [leoforfree/cz-customizable on GitHub](https://github.com/leoforfree/cz-customizable)
- [License: MIT](https://github.com/leoforfree/cz-customizable/blob/master/LICENSE)
- [README](https://github.com/leoforfree/cz-customizable/blob/master/README.md)
- [Releases](https://github.com/leoforfree/cz-customizable/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/leoforfree-cz-customizable