cz-cubics

A customizable Commitizen adapter with emoji-prefixed conventional commit messages, plus a ready-to-extend commitlint config.

Installation

pnpm add -D cz-cubics commitizen

Register it as your Commitizen adapter in package.json:

{
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-cubics"
    }
  }
}

or in .czrc:

{
  "path": "./node_modules/cz-cubics"
}

Then commit with:

pnpm commit

(assuming a "commit": "cz" script, or run commitizen/git cz directly)

Configuration

Config is resolved from the nearest of the following files, searched via find-up in this order:

1. .czrc
2. package.json

The first matching file that contains a config["cz-cubics"] key wins if both exist, .czrc takes precedence.

Config file shape

.czrc

{
  "config": {
    "cz-cubics": {
      "headFormat": "{type}{scope}: {subject}"
    }
  }
}

package.json

{
  "config": {
    "commitizen": {
      "path": "node_modules/cz-cubics"
    },
    "cz-cubics": {
      "headFormat": "{type}{scope}: {subject}"
    }
  }
}

Note cz-cubics sits as a sibling of commitizen under config, not nested inside it.

Custom configurations will be validated, invalid types, unknown skipQuestions values, or unrecognized {token}s in headFormat throws errors, rather than failing silently or on the first issue.

CZCubicsConfig

CZCubicsCommitType

Each entry in types (and in defaultTypes.json) has the shape:

{
  "name": "feat",
  "emoji": "✨",
  "description": "A new feature"
}

headFormat tokens (CZCubicsHeaderTokens)

Any run of consecutive whitespace left behind by an omitted token (e.g. no scope) is collapsed to a single space.

Example .czrc

{
  "config": {
    "cz-cubics": {
      "types": [
        { "name": "feat", "emoji": "✨", "description": "A new feature" },
        { "name": "fix", "emoji": "🐛", "description": "A bug fix" }
      ],
      "scopes": ["api", "ui", "docs"],
      "skipQuestions": ["issues", "breaking"],
      "subjectMaxLength": 72,
      "headFormat": "{emoji} {type}{scope}: {subject}"
    }
  }
}

Commit message structure

The final message is assembled as:

<head>

<body>

BREAKING CHANGE: <breakingBody>

<footer (issues)>

• head => built from headFormat, truncated to the terminal's column width.
• body => the free-text body answer, wrapped to the terminal width. Newline can be added by using a pipe |
• breaking => included only if a breaking change body was provided. Newline can be added by using a pipe |
• footer => issue references, formatted via formatIssues.

Empty sections are omitted; the result is trimmed of trailing whitespace.

commitlint integration

This package ships its own commitlint.config.js, which consumers can extend directly instead of duplicating rules:

/** @type {import("@commitlint/types").UserConfig} */
module.exports = {
  extends: ["./node_modules/cz-cubics/commitlint.config.js"],
  // add or override rules here
};

when the type in package.json is "module" the cjs version can be used instead

/** @type {import("@commitlint/types").UserConfig} */
module.exports = {
  extends: ["./node_modules/cz-cubics/commitlint.config.cjs"],
  // add or override rules here
};

It includes:

• type-empty: never,
• subject-empty: never,
• subject-case: sentence-case, always enforced.
• subject-max-length: 100, always enforced, taken from your resolved subjectMaxLength config.
• type-enum: restricted to the name of each entry in your resolved types config, so only your configured commit types pass.
• header-start-emoji: always enforced the header must start with an Extended_Pictographic character (an emoji), matching the leading {emoji} token in headFormat.
• header-has-emoji: off by default (severity 0) same emoji detection, but checks the entire header line rather than just the leading token. Enable it (severity 2) with "always" if you want emoji allowed anywhere in the header rather than only at the start.
• A parserPreset whose headerPattern and headerCorrespondence are built dynamically from your resolved headFormat, rather than hardcoded. This means:
  • Changing headFormat in your config automatically changes what the linter parses and validates.
  • Required tokens ({type}, {subject}) use a matching strategy that still lets the overall header parse successfully even when one of them is empty
  • Optional tokens ({emoji}, {scope}) are correctly treated as absent when omitted, rather than requiring a placeholder value.

Requirements

cz-cubics/commitlint.config.js is a plain config object with no runtime dependency on any commitlint package itself. However, to actually lint commits you need @commitlint/cli installed in your own project, since that's what reads and executes the config:

pnpm add -D @commitlint/cli

Husky hook

Wire it up in .husky/commit-msg:

pnpm commitlint --edit "$1"

Make sure the hook file is executable (chmod +x .husky/commit-msg) and that core.hooksPath points at .husky (set automatically by the prepare: "husky" script).

License

MIT

Special Thanks

• ngryman/cz-emoji: the core idea of emoji-based conventional commit types this adapter builds on.
• commitizen/cz-cli: the adapter framework this package plugs into.