or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mdconfiguration.mdcore-orchestration.mdgit-operations.mdgithub-integration.mdgitlab-integration.mdindex.mdnpm-publishing.mdplugin-system.md
tile.json

tessl/npm-release-it

Generic CLI tool to automate versioning and package publishing-related tasks.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/release-it@19.0.x

To install, run

npx @tessl/cli install tessl/npm-release-it@19.0.0

index.mddocs/

Release It!

Release It! is a comprehensive CLI tool and JavaScript library for automating software release workflows. It provides a complete solution for version management, Git operations, changelog generation, and publishing to various platforms including npm, GitHub, and GitLab. The tool features a powerful plugin system, configurable hooks, and supports both interactive and automated CI/CD environments.

Package Information

  • Package Name: release-it
  • Package Type: npm
  • Language: JavaScript/Node.js
  • Installation: npm install -D release-it or npm install -g release-it

Core Imports

import runTasks from "release-it";
import { Config, Plugin } from "release-it";

For CommonJS:

const runTasks = require("release-it");
const { Config, Plugin } = require("release-it");

Basic Usage

CLI Usage

# Basic release with prompts
npx release-it

# Specify version increment
npx release-it minor

# Dry run mode
npx release-it --dry-run

# CI mode (non-interactive)
npx release-it --ci

# Configuration file
npx release-it --config .release-it.json

Programmatic Usage

import runTasks from "release-it";

// Basic programmatic release
const result = await runTasks({
  increment: "patch",
  "dry-run": false
});

console.log(result.version); // "1.2.3"

Architecture

Release It! is built around several key architectural components:

  • Main Orchestrator: Core runTasks function that manages the complete release workflow
  • Plugin System: Extensible architecture with built-in plugins for Git, npm, GitHub, GitLab, and version management
  • Configuration Management: Hierarchical configuration system supporting local files, package.json, and CLI arguments
  • Lifecycle Hooks: Comprehensive hook system for executing custom commands at any stage
  • Interactive/CI Modes: Dual operation modes supporting both interactive prompts and automated CI/CD workflows
  • Context System: Shared context across plugins for maintaining state and templates

Capabilities

Core Release Orchestration

Main entry point for executing complete release workflows with plugin coordination and lifecycle management.

/**
 * Execute complete release workflow with plugin orchestration
 * @param options - Release configuration options
 * @param dependencies - Optional dependency injection container
 * @returns Promise resolving to release results
 */
function runTasks(
  options: ReleaseOptions,
  dependencies?: DependencyContainer
): Promise<ReleaseResult>;

interface ReleaseResult {
  name: string;
  changelog: string;
  latestVersion: string;
  version: string;
}

interface ReleaseOptions {
  increment?: string | boolean;
  "dry-run"?: boolean;
  verbose?: boolean | number;
  ci?: boolean;
  "only-version"?: boolean;
  "release-version"?: boolean;
  changelog?: boolean;
  config?: string | boolean;
  [key: string]: any;
}

interface DependencyContainer {
  config?: Config;
  log?: Logger;
  shell?: Shell;
  spinner?: Spinner;
  prompt?: Prompt;
}

interface Logger {
  log(message: string): void;
  info(message: string): void;
  warn(message: string): void;
  error(message: string): void;
  obtrusive(message: string): void;
  preview(options: { title: string; text: string }): void;
}

interface Shell {
  exec(command: string, options?: ExecOptions, context?: any): Promise<string>;
}

interface Spinner {
  show(options: SpinnerOptions): Promise<any>;
}

interface Prompt {
  register(prompts: any, namespace: string): void;
  show(options: PromptOptions): Promise<any>;
}

interface ExecOptions {
  external?: boolean;
  write?: boolean;
}

interface SpinnerOptions {
  task: () => Promise<any>;
  label: string;
  context?: any;
  external?: boolean;
}

interface PromptOptions {
  type?: string;
  name?: string;
  message?: string;
  choices?: any[];
  default?: any;
  namespace?: string;
}

Core Orchestration

Configuration Management

Comprehensive configuration system with hierarchical loading, validation, and context management.

class Config {
  constructor(config?: any);
  
  /** Initialize configuration from files and defaults */
  init(): Promise<void>;
  
  /** Get configuration context with optional path */
  getContext(path?: string): any;
  
  /** Set context options */
  setContext(options: any): void;
  
  /** Set CI mode */
  setCI(value?: boolean): void;
  
  /** Configuration properties (read-only) */
  get isDryRun(): boolean;
  get isIncrement(): boolean;
  get isVerbose(): boolean;
  get verbosityLevel(): number;
  get isDebug(): boolean;
  get isCI(): boolean;
  get isPromptOnlyVersion(): boolean;
  get isReleaseVersion(): boolean;
  get isChangelog(): boolean;
  get options(): any;
  get localConfig(): any;
  get defaultConfig(): any;
}

Configuration

Plugin System

Extensible plugin architecture for implementing release functionality with lifecycle hooks.

class Plugin {
  constructor(options: PluginOptions);
  
  /** Static methods */
  static isEnabled(): boolean;
  static disablePlugin(): null;
  
  /** Plugin lifecycle hooks */
  init(): Promise<void>;
  getName(): string | Promise<string>;
  getLatestVersion(): string | Promise<string>;
  getChangelog(latestVersion?: string): string | Promise<string>;
  getIncrement(incrementBase: IncrementBase): string | Promise<string>;
  getIncrementedVersionCI(incrementBase: IncrementBase): string | Promise<string>;
  getIncrementedVersion(incrementBase: IncrementBase): string | Promise<string>;
  beforeBump(): Promise<void>;
  bump(version: string): Promise<boolean>;
  beforeRelease(): Promise<void>;
  release(): Promise<boolean>;
  afterRelease(): Promise<void>;
  
  /** Context management */
  getContext(path?: string): any;
  setContext(context: any): void;
  
  /** Plugin utilities */
  exec(command: string, options?: { options?: any; context?: any }): Promise<string>;
  step(options: StepOptions): Promise<any>;
  registerPrompts(prompts: any): void;
  showPrompt(options: PromptOptions): Promise<any>;
  
  /** Plugin configuration */
  getInitialOptions(options: any, namespace: string): any;
}

interface PluginOptions {
  namespace: string;
  options?: any;
  container?: DependencyContainer;
}

interface IncrementBase {
  latestVersion: string;
  increment: string;
  isPreRelease: boolean;
  preReleaseId: string;
  preReleaseBase: string;
}

interface StepOptions {
  task?: () => Promise<any>;
  label?: string;
  prompt?: string;
  type?: string;
  choices?: any[];
  transformer?: (value: any) => any;
  context?: any;
}

Plugin System

Git Operations

Comprehensive Git functionality for commits, tags, pushes, and repository management.

class Git extends Plugin {
  /** Static methods */
  static isEnabled(options: any): Promise<boolean>;
  
  /** Git status and validation */
  isWorkingDirClean(): Promise<boolean>;
  hasUpstreamBranch(): Promise<boolean>;
  tagExists(tag: string): Promise<boolean>;
  isRequiredBranch(pattern: string): Promise<boolean>;
  
  /** Git operations */
  stage(file: string): Promise<void>;
  stageDir(options?: { baseDir?: string }): Promise<void>;
  reset(file: string): Promise<void>;
  status(): Promise<string>;
  commit(options?: CommitOptions): Promise<void>;
  tag(options?: TagOptions): Promise<void>;
  push(options?: PushOptions): Promise<void>;
  
  /** Git information */
  getBranchName(): Promise<string>;
  getLatestTagName(): Promise<string>;
  getCommitsSinceLatestTag(path?: string): Promise<number>;
  getRemoteUrl(): Promise<string>;
  getRemote(): Promise<string>;
  getRemoteForBranch(branch: string): Promise<string>;
  getSecondLatestTagName(latestTag: string): Promise<string>;
  getUpstreamArgs(pushRepo?: string): Promise<string[]>;
  
  /** Rollback functionality */
  enableRollback(): void;
  disableRollback(): void;
  rollback(): void;
  rollbackTagPush(): Promise<void>;
  
  /** Git utilities */
  fetch(remoteUrl: string): Promise<void>;
  isRemoteName(remoteUrlOrName: string): boolean;
}

interface CommitOptions {
  message?: string;
  args?: string[];
}

interface TagOptions {
  name?: string;
  annotation?: string;
  args?: string[];
}

interface PushOptions {
  args?: string[];
}

Git Operations

npm Publishing

Complete npm package publishing functionality with registry validation and authentication.

class npm extends Plugin {
  /** Static methods */
  static isEnabled(options: any): boolean;
  
  /** Registry operations */
  isRegistryUp(): Promise<boolean>;
  isAuthenticated(): Promise<boolean>;
  isCollaborator(): Promise<boolean>;
  
  /** Version management */
  getLatestRegistryVersion(): Promise<string | null>;
  resolveTag(version: string): Promise<string>;
  guessPreReleaseTag(): Promise<string>;
  getRegistryPreReleaseTags(): Promise<string[]>;
  
  /** Registry information */
  getPackageUrl(): string;
  getRegistry(): string | undefined;
  getPublicPath(): string;
  
  /** Publishing */
  publish(options?: PublishOptions): Promise<boolean | void>;
}

interface PublishOptions {
  otp?: string;
  otpCallback?: () => Promise<string>;
}

npm Publishing

GitHub Integration

GitHub releases, asset uploads, and repository integration.

class GitHub extends Plugin {
  /** Authentication and validation */
  isAuthenticated(): Promise<boolean>;
  isCollaborator(): Promise<boolean>;
  
  /** Release management */
  createRelease(): Promise<Release>;
  updateRelease(): Promise<boolean>;
  getLatestRelease(): Promise<Release>;
  createWebRelease(): Promise<void>;
  generateWebUrl(): Promise<string>;
  
  /** Asset management */
  uploadAsset(filePath: string): Promise<any>;
  uploadAssets(): Promise<void>;
  
  /** Repository information */
  getWebUrl(): string;
  getChangelog(): Promise<string>;
  getReleaseUrlFallback(tagName: string): string;
  
  /** Comments and interaction */
  commentOnResolvedItems(): Promise<void>;
  getCommits(): Promise<any[]>;
  renderReleaseNotes(releaseNotes: any): Promise<string>;
  
  /** Client and utilities */
  get client(): any;
  retry(fn: () => Promise<any>): Promise<any>;
  handleError(err: any, bail: boolean): void;
  getOctokitReleaseOptions(options?: any): Promise<any>;
}

interface CreateReleaseOptions {
  name?: string;
  tag_name?: string;
  body?: string;
  draft?: boolean;
  prerelease?: boolean;
  make_latest?: boolean | 'legacy';
  discussion_category_name?: string;
}

interface Release {
  id: number;
  html_url: string;
  upload_url: string;
  tag_name: string;
  name: string;
  body: string;
  draft: boolean;
  prerelease: boolean;
}

GitHub Integration

GitLab Integration

GitLab releases, asset uploads, and repository integration for both GitLab.com and self-hosted instances.

class GitLab extends Plugin {
  /** Authentication and validation */
  isAuthenticated(): Promise<boolean>;
  isCollaborator(): Promise<boolean>;
  
  /** Release management */
  createRelease(): Promise<boolean>;
  checkReleaseMilestones(): Promise<void>;
  getReleaseMilestones(): string[];
  
  /** Asset management */
  uploadAsset(filePath: string): Promise<any>;
  uploadAssets(): Promise<void>;
  
  /** Repository information */
  getWebUrl(): string;
  getChangelog(): Promise<string>;
  
  /** API utilities */
  request(endpoint: string, options?: any): Promise<any>;
}

interface GitLabRelease {
  id: number;
  name: string;
  tag_name: string;
  description: string;
  _links: {
    self: string;
  };
}

GitLab Integration

CLI Interface

Command-line interface utilities and argument parsing.

/**
 * Main CLI entry point
 * @param options - Parsed CLI options
 * @returns Promise resolving when CLI operation completes
 */
function cli(options: CLIOptions): Promise<any>;

/**
 * Parse CLI arguments into options object
 * @param args - Command line arguments
 * @returns Parsed options object
 */
function parseCliArguments(args: string[]): CLIOptions;

/** Print version information */
function version(): void;

/** Print help text */
function help(): void;

interface CLIOptions {
  increment?: string;
  "dry-run"?: boolean;
  verbose?: boolean | number;
  ci?: boolean;
  "only-version"?: boolean;
  "release-version"?: boolean;
  changelog?: boolean;
  config?: string;
  help?: boolean;
  version?: boolean;
  [key: string]: any;
}

CLI Interface