tessl/npm-standard-version

A Node.js command-line tool that automates versioning and changelog generation for projects following the Conventional Commits specification.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Standard Version

Name: tessl/npm-standard-version
Author: tessl

Standard Version is a Node.js command-line tool that automates versioning and changelog generation for projects following the Conventional Commits specification. It provides a complete workflow for semantic versioning by analyzing commit messages to determine version bumps, automatically updating package.json and other metadata files, generating detailed changelogs using conventional-changelog, and creating git tags for releases.

Package Information

Package Name: standard-version
Package Type: npm
Language: JavaScript
Installation: npm install standard-version

Core Imports

const standardVersion = require('standard-version');

For CLI usage:

npx standard-version
# or globally: npm install -g standard-version
standard-version

Basic Usage

CLI Usage

# Standard release (analyzes commits and bumps version accordingly)
standard-version

# Specific release type
standard-version --release-as major
standard-version --release-as minor
standard-version --release-as patch

# Pre-release
standard-version --prerelease
standard-version --prerelease alpha

# First release
standard-version --first-release

# Dry run (see what would be done)
standard-version --dry-run

Programmatic Usage

const standardVersion = require('standard-version');

// Basic usage with default options
await standardVersion({});

// With custom options
await standardVersion({
  releaseAs: 'minor',
  infile: 'CHANGELOG.md',
  silent: false,
  dryRun: true
});

Architecture

Standard Version is built around several key components:

CLI Interface: Command-line parser with comprehensive option support via yargs
Core Workflow: Orchestrates bump, changelog, commit, and tag lifecycles
File Updater System: Pluggable system for updating version in different file formats (JSON, plain text, custom)
Lifecycle Hooks: Pre/post hooks for each stage (prebump, precommit, etc.)
Configuration System: Support for multiple configuration file formats
Conventional Changelog Integration: Uses conventional-changelog for changelog generation

Capabilities

Command Line Interface

Complete CLI tool with comprehensive option support for automated versioning workflows. Supports both interactive and CI/CD usage patterns.

# Core CLI options
standard-version [options]

--release-as, -r <release-type>     # major|minor|patch or specific version
--prerelease, -p [tag]             # Make pre-release with optional tag
--first-release, -f                # Mark as first release
--dry-run                          # Preview changes without executing
--silent                           # Suppress output
--sign, -s                         # Sign git commit and tag
--no-verify, -n                    # Bypass git hooks
--tag-prefix, -t <prefix>          # Custom git tag prefix (default: 'v')

Command Line Interface

Programmatic API

Node.js API for integrating standard-version into build scripts and automation workflows.

/**
 * Main function for programmatic usage
 * @param {Object} argv - Configuration options object
 * @returns {Promise<void>} Promise that resolves when process completes
 */
async function standardVersion(argv);

Programmatic API

Configuration System

Flexible configuration system supporting multiple file formats and package.json integration.

/**
 * Load configuration from standard-version config files
 * @returns {Object} Configuration object
 */
function getConfiguration();

Configuration

File Updater System

Pluggable system for updating version numbers in different file formats with support for custom updaters.

/**
 * Resolve updater from file path or configuration object
 * @param {string|Object} arg - File path or updater configuration
 * @returns {Object|false} Updater object or false if invalid
 */
function resolveUpdaterObjectFromArgument(arg);

interface Updater {
  readVersion(contents: string): string;
  writeVersion(contents: string, version: string): string;
  isPrivate?(contents: string): boolean;
}

File Updaters

Lifecycle Management

Complete lifecycle management with hooks for customizing the versioning workflow at each stage.

/**
 * Execute lifecycle script for given hook
 * @param {Object} args - Configuration object
 * @param {string} hookName - Name of lifecycle hook
 * @returns {Promise<string>} Promise resolving to script output
 */
async function runLifecycleScript(args, hookName);

Lifecycle Hooks

Types

interface StandardVersionOptions {
  // Release configuration
  releaseAs?: string;              // Release type or specific version
  prerelease?: string | boolean;   // Pre-release tag or true for default
  firstRelease?: boolean;          // Mark as first release
  
  // File configuration
  infile?: string;                 // Changelog file path (default: 'CHANGELOG.md')
  packageFiles?: string[];         // Files to read version from
  bumpFiles?: string[];           // Files to update with new version
  
  // Git configuration
  sign?: boolean;                  // Sign git commit and tag
  noVerify?: boolean;              // Bypass git hooks
  commitAll?: boolean;             // Commit all staged changes
  tagPrefix?: string;              // Git tag prefix (default: 'v')
  
  // Behavior configuration
  silent?: boolean;                // Suppress output
  dryRun?: boolean;               // Preview mode without changes
  gitTagFallback?: boolean;        // Use git tags if no package file found
  
  // Advanced configuration
  scripts?: Record<string, string>; // Lifecycle hook scripts
  skip?: Record<string, boolean>;   // Skip specific steps
  preset?: string;                  // Conventional changelog preset
  path?: string;                   // Only include commits under path
  lernaPackage?: string;           // Package name for Lerna monorepo tag extraction
  header?: string;                 // Custom changelog header
  releaseCommitMessageFormat?: string; // Custom commit message template
}

interface ValidationSchema {
  scripts?: Record<string, string>;
  skip?: Record<string, boolean>;
}