or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-cz-conventional-changelog

Commitizen adapter following the conventional-changelog format for standardized commit messages.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/cz-conventional-changelog@3.3.x

To install, run

npx @tessl/cli install tessl/npm-cz-conventional-changelog@3.3.0

index.mddocs/

cz-conventional-changelog

A commitizen adapter that implements the conventional changelog format for creating standardized commit messages. This adapter provides an interactive prompting interface that guides developers through creating consistent, structured commit messages following conventional commit standards.

Package Information

  • Package Name: cz-conventional-changelog
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install cz-conventional-changelog

Core Imports

// Direct usage (when configured as commitizen adapter)
const adapter = require('cz-conventional-changelog');

For commitizen configuration in package.json:

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

Basic Usage

The package is primarily used as a commitizen adapter. After installation and configuration, use with:

# Using git-cz (commitizen CLI)
git add .
git cz

The adapter will prompt you through creating a conventional commit message following the format:

type(scope): subject

body

BREAKING CHANGE: breaking change description

issue references

Capabilities

Commitizen Adapter

Provides a complete commitizen adapter object with interactive prompting functionality. The main module export is a function that takes configuration options and returns a commitizen adapter object.

/**
 * Main export - factory function that creates a commitizen adapter
 * @param {Object} options - Configuration options for the adapter
 * @returns {Object} Commitizen adapter object with prompter function
 */
function createAdapter(options) {
  return {
    prompter: function(cz, commit) { /* implementation */ }
  };
}

// Default export (index.js) pre-configures and returns the adapter
module.exports = createAdapter(configuredOptions);

Prompter Function

The core prompter function that guides users through conventional commit creation.

/**
 * The prompter function guides users through conventional commit creation
 * @param {Object} cz - Inquirer.js instance for prompting  
 * @param {Function} commit - Callback function to execute with final commit message
 * @returns {void}
 */
function prompter(cz, commit);

Interactive Prompts:

The prompter function guides users through the following sequence of questions:

  1. Commit Type: Select from conventional commit types (feat, fix, docs, etc.)
  2. Scope: Optional scope of the change (component, file name, etc.) - automatically lowercased unless disabled
  3. Subject: Short, imperative description of the change with length validation and live character count
  4. Body: Optional longer description providing more detail
  5. Breaking Changes Confirmation: "Are there any breaking changes?" (yes/no)
  6. Breaking Body (conditional): Required body text if breaking changes exist but no body was provided
  7. Breaking Description (conditional): Description of the breaking changes if confirmed
  8. Issues Affected Confirmation: "Does this change affect any open issues?" (yes/no)
  9. Issues Body (conditional): Required body text if issues are affected but no body was provided
  10. Issue References (conditional): Issue references in format "fix #123", "re #123" if issues are affected

Configuration Options

All configuration options can be set in package.json under config.commitizen or via environment variables.

interface ConfigurationOptions {
  /** Custom commit types object */
  types?: { [key: string]: { description: string; title: string } };
  
  /** Default commit type selection */
  defaultType?: string;
  
  /** Default scope value */
  defaultScope?: string;
  
  /** Default subject text */
  defaultSubject?: string;
  
  /** Default body text */
  defaultBody?: string;
  
  /** Default issues reference text */
  defaultIssues?: string;
  
  /** Disable automatic lowercase conversion of scope */
  disableScopeLowerCase?: boolean;
  
  /** Disable automatic lowercase conversion of subject */
  disableSubjectLowerCase?: boolean;
  
  /** Maximum width for commit header (default: 100) */
  maxHeaderWidth?: number;
  
  /** Maximum width for commit body lines (default: 100) */
  maxLineWidth?: number;
}

Environment Variable Overrides:

// Environment variables that override configuration
const environmentVariables = {
  CZ_TYPE: "defaultType",
  CZ_SCOPE: "defaultScope", 
  CZ_SUBJECT: "defaultSubject",
  CZ_BODY: "defaultBody",
  CZ_ISSUES: "defaultIssues",
  CZ_MAX_HEADER_WIDTH: "maxHeaderWidth",
  CZ_MAX_LINE_WIDTH: "maxLineWidth",
  DISABLE_SCOPE_LOWERCASE: "disableScopeLowerCase",
  DISABLE_SUBJECT_LOWERCASE: "disableSubjectLowerCase"
};

Custom Commit Types

Define custom commit types in your configuration:

{
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog",
      "types": {
        "feat": {
          "description": "A new feature",
          "title": "Features"
        },
        "fix": {
          "description": "A bug fix", 
          "title": "Bug Fixes"
        },
        "docs": {
          "description": "Documentation changes",
          "title": "Documentation"
        },
        "style": {
          "description": "Code style changes",
          "title": "Styles"
        },
        "refactor": {
          "description": "Code refactoring",
          "title": "Code Refactoring"
        },
        "test": {
          "description": "Adding or updating tests",
          "title": "Tests"
        },
        "chore": {
          "description": "Other changes",
          "title": "Chores"
        }
      }
    }
  }
}

Commitlint Integration

The adapter automatically integrates with commitlint for header length validation:

/**
 * Automatic commitlint integration
 * If @commitlint/load is available, the adapter will:
 * - Load commitlint configuration
 * - Use header-max-length rule for maxHeaderWidth if not explicitly set
 * - Override package.json and environment variable settings
 */

Usage Examples

Basic Configuration

{
  "devDependencies": {
    "commitizen": "^4.0.3",
    "cz-conventional-changelog": "^3.3.0"
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  },
  "scripts": {
    "commit": "git-cz"
  }
}

Advanced Configuration

{
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog",
      "maxHeaderWidth": 72,
      "maxLineWidth": 100,
      "defaultType": "feat",
      "defaultScope": "core",
      "disableScopeLowerCase": true,
      "disableSubjectLowerCase": false
    }
  }
}

Environment Variable Usage

# Set defaults via environment variables
export CZ_TYPE="fix"
export CZ_SCOPE="auth"
export CZ_MAX_HEADER_WIDTH="50"

# Run commitizen
git cz

Programmatic Usage

const adapter = require('cz-conventional-changelog');

// The adapter object contains the prompter function
// Typically used by commitizen CLI, but can be used programmatically
console.log(typeof adapter.prompter); // "function"

Output Format

The adapter generates commit messages in conventional changelog format:

type(scope): subject

Optional body paragraph providing more detail about the change.
Can be multiple lines and should wrap at the configured maxLineWidth.

BREAKING CHANGE: Description of breaking changes if any exist.
This section appears when breaking changes are indicated.

Closes #123, #456

Examples:

  • feat(auth): add OAuth2 login support
  • fix(parser): handle edge case in URL parsing
  • docs: update installation instructions
  • refactor!: change API response format

Dependencies

The adapter requires the following runtime dependencies:

  • commitizen: Configuration loading and CLI integration
  • conventional-commit-types: Standard commit type definitions
  • chalk: Terminal color output for validation feedback
  • word-wrap: Text wrapping for commit body formatting
  • lodash.map: Array mapping utility
  • longest: Find longest string utility for formatting

Optional dependency:

  • @commitlint/load: For commitlint configuration integration