or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

adapter.md cache.md cli.md commit.md config.md git.md index.md init.md staging.md

tile.json

Project Initialization

Adapter installation and project configuration functionality for setting up commitizen in new and existing projects.

Capabilities

Initialize Adapter

Main initialization function that installs adapters and configures projects for commitizen usage.

/**
 * Installs commitizen adapter and configures project
 * @param repoPath - Path to repository root
 * @param adapterNpmName - NPM package name of adapter to install
 * @param options - Installation and configuration options
 * @throws Error if required arguments are missing or installation fails
 */
function init(
  repoPath: string,
  adapterNpmName: string,
  options?: InitOptions
): void;

interface InitOptions {
  save?: boolean;              // Add to dependencies (npm)
  saveDev?: boolean;           // Add to devDependencies (npm/pnpm)
  saveExact?: boolean;         // Install exact version (npm/pnpm)
  force?: boolean;             // Force install over existing adapter
  yarn?: boolean;              // Use yarn package manager
  dev?: boolean;               // Add to devDependencies (yarn)
  exact?: boolean;             // Install exact version (yarn)
  pnpm?: boolean;              // Use pnpm package manager
  includeCommitizen?: boolean; // Also install commitizen package
}

Usage Examples:

const { init } = require('commitizen');

// Basic initialization with npm
init(process.cwd(), 'cz-conventional-changelog', {
  saveDev: true,
  saveExact: true
});

// Force installation over existing adapter
init(process.cwd(), 'cz-conventional-changelog', {
  saveDev: true,
  force: true
});

// Yarn installation
init(process.cwd(), 'cz-conventional-changelog', {
  yarn: true,
  dev: true,
  exact: true
});

// pnpm installation with commitizen included
init(process.cwd(), 'cz-conventional-changelog', {
  pnpm: true,
  saveDev: true,
  saveExact: true,
  includeCommitizen: true
});

Default Options

The initialization function uses sensible defaults for most scenarios:

const defaultInitOptions: InitOptions = {
  save: false,           // Don't add to dependencies by default
  saveDev: true,         // Add to devDependencies by default
  saveExact: false,      // Allow version ranges by default
  force: false,          // Don't force install by default
  yarn: false,           // Use npm by default
  dev: true,             // Add to devDependencies (yarn equivalent)
  exact: false,          // Allow version ranges (yarn equivalent)
  pnpm: false,           // Use npm by default
};

Argument Validation

Built-in validation ensures required parameters are provided:

/**
 * Validates required arguments for initialization
 * @param path - Repository path (must be provided)
 * @param adapterNpmName - Adapter package name (must be provided)
 * @throws Error if required arguments are missing
 */
function checkRequiredArguments(path: string, adapterNpmName: string): void;

Configuration Loading

Loads existing adapter configuration to prevent conflicts:

/**
 * Loads existing adapter configuration from project
 * @param cwd - Working directory to search for config
 * @returns Existing commitizen configuration or undefined
 */
function loadAdapterConfig(cwd: string): CommitizenConfig | undefined;

interface CommitizenConfig {
  path: string;          // Path to adapter module
}

Installation Process

The initialization process follows these steps:

Argument Validation: Ensures required parameters are provided
Configuration Check: Loads existing adapter configuration
Conflict Resolution: Checks for existing adapters (fails unless force: true)
Package Manager Selection: Chooses npm, yarn, or pnpm based on options
Flag Mapping: Maps generic options to package manager-specific flags
Command Generation: Creates appropriate install command string
Adapter Installation: Executes package manager install command
Commitizen Installation: Optionally installs commitizen if includeCommitizen: true
Configuration Update: Updates package.json with adapter path configuration

Package Manager Support

NPM Installation

# Generated command example
npm install cz-conventional-changelog --save-dev --save-exact

// Usage
init(process.cwd(), 'cz-conventional-changelog', {
  saveDev: true,
  saveExact: true
});

Yarn Installation

# Generated command example  
yarn add cz-conventional-changelog --dev --exact

// Usage
init(process.cwd(), 'cz-conventional-changelog', {
  yarn: true,
  dev: true,
  exact: true
});

PNPM Installation

# Generated command example
pnpm add cz-conventional-changelog --save-dev --save-exact

// Usage
init(process.cwd(), 'cz-conventional-changelog', {
  pnpm: true,
  saveDev: true,
  saveExact: true
});

Configuration Output

After successful initialization, the following configuration is added to package.json:

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

Error Handling

Initialization handles various error conditions:

Missing Arguments: Clear error messages for required parameters
Existing Configuration: Prevents accidental overwrite unless force: true
Installation Failures: Reports package manager errors with context
File System Errors: Handles permission issues and missing directories
Invalid Adapters: Validates adapter package names and availability

Error Examples:

// Missing required arguments
try {
  init(); // Missing both arguments
} catch (error) {
  console.error(error.message); // "Path is required when running init."
}

// Existing adapter without force flag
try {
  init(process.cwd(), 'new-adapter'); // Existing adapter configured
} catch (error) {
  console.error(error.message);
  // "A previous adapter is already configured. Use --force to override"
}

// Installation failure
try {
  init(process.cwd(), 'nonexistent-adapter');
} catch (error) {
  console.error('Installation failed:', error.message);
}

Advanced Usage

Custom Adapter Paths

Initialize with local or custom adapter paths:

// Local adapter
init(process.cwd(), './custom-adapters/my-adapter', {
  saveDev: true
});

// Scoped package
init(process.cwd(), '@company/cz-adapter', {
  saveDev: true,
  saveExact: true
});

Multi-Package Installation

Install commitizen along with the adapter:

init(process.cwd(), 'cz-conventional-changelog', {
  saveDev: true,
  includeCommitizen: true  // Also installs commitizen package
});