tessl/npm-standard-version

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

—

Pending

Overview

Eval results

Files

Configuration

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

Standard Version supports flexible configuration through multiple file formats and package.json integration. Configuration allows customization of versioning behavior, lifecycle hooks, file handling, and integration with conventional changelog presets.

Capabilities

Configuration File Loading

Automatic discovery and loading of configuration from standard locations.

/**
 * Load and merge configuration from all available sources
 * @returns {Object} Merged configuration object
 * @throws {Error} If configuration file contains invalid format or structure
 */
function getConfiguration();

Usage Examples:

const { getConfiguration } = require('standard-version/lib/configuration');

// Load configuration automatically
const config = getConfiguration();
console.log('Active configuration:', config);

// Configuration is loaded from first found file:
// 1. .versionrc
// 2. .versionrc.cjs  
// 3. .versionrc.json
// 4. .versionrc.js
// 5. package.json (under "standard-version" key)

Configuration File Formats

Standard Version supports multiple configuration file formats for different project needs.

JSON Configuration (.versionrc, .versionrc.json):

{
  "tagPrefix": "v",
  "releaseCommitMessageFormat": "chore(release): {{currentTag}}",
  "scripts": {
    "prebump": "echo 'Starting version bump'",
    "postbump": "npm run build",
    "precommit": "npm run test",
    "posttag": "npm publish"
  },
  "skip": {
    "changelog": false,
    "tag": false
  },
  "packageFiles": [
    "package.json",
    "manifest.json"
  ],
  "bumpFiles": [
    "package.json",
    "manifest.json",
    "version.txt"
  ],
  "infile": "CHANGELOG.md",
  "header": "# Release Notes\n\nAll notable changes will be documented in this file.\n"
}

JavaScript Configuration (.versionrc.js, .versionrc.cjs):

// .versionrc.js - ES modules
export default {
  tagPrefix: 'release-',
  scripts: {
    prebump: 'npm run validate',
    postbump: process.env.CI ? 'npm run build:prod' : 'npm run build:dev'
  },
  skip: {
    changelog: process.env.SKIP_CHANGELOG === 'true',
    tag: process.env.DRY_RUN === 'true'
  }
};

// .versionrc.cjs - CommonJS
module.exports = {
  tagPrefix: 'v',
  scripts: {
    prebump: 'npm run lint && npm run test',
    postbump: 'npm run build'
  }
};

// Function-based configuration
module.exports = function() {
  return {
    tagPrefix: process.env.TAG_PREFIX || 'v',
    silent: process.env.CI === 'true',
    dryRun: process.env.DRY_RUN === 'true'
  };
};

Package.json Integration:

{
  "name": "my-package", 
  "version": "1.0.0",
  "standard-version": {
    "tagPrefix": "v",
    "scripts": {
      "prebump": "npm run test",
      "postbump": "npm run build"
    },
    "skip": {
      "changelog": false
    }
  }
}

Core Configuration Options

Essential configuration options for controlling standard-version behavior.

interface CoreConfiguration {
  // Version and release configuration
  tagPrefix?: string;                    // Prefix for git tags (default: 'v')
  releaseCommitMessageFormat?: string;   // Template for release commit message
  firstRelease?: boolean;                // Skip version bump for initial release
  
  // File handling configuration
  infile?: string;                       // Changelog file path (default: 'CHANGELOG.md')
  packageFiles?: string[];               // Files to read version from
  bumpFiles?: string[];                 // Files to update with new version
  
  // Behavior configuration
  silent?: boolean;                      // Suppress output messages
  dryRun?: boolean;                     // Preview changes without executing
  gitTagFallback?: boolean;              // Use git tags if no package files found
  
  // Git configuration
  sign?: boolean;                        // Sign commits and tags with GPG
  noVerify?: boolean;                   // Bypass git hooks during commit
  commitAll?: boolean;                   // Commit all staged changes
}

Usage Examples:

{
  "tagPrefix": "release-",
  "releaseCommitMessageFormat": "build: release {{currentTag}}",
  "infile": "HISTORY.md",
  "packageFiles": ["package.json", "pyproject.toml"],
  "bumpFiles": ["package.json", "pyproject.toml", "VERSION"],
  "silent": false,
  "dryRun": false,
  "gitTagFallback": true,
  "sign": true,
  "noVerify": false,
  "commitAll": false
}

Lifecycle Hook Scripts

Configure custom scripts to run at different stages of the release process.

interface LifecycleScripts {
  prebump?: string;      // Before version calculation and file updates
  postbump?: string;     // After version bump but before changelog
  prechangelog?: string; // Before changelog generation
  postchangelog?: string;// After changelog generation but before commit
  precommit?: string;    // Before git commit
  postcommit?: string;   // After git commit but before tag
  pretag?: string;       // Before git tag creation
  posttag?: string;      // After git tag creation (final step)
}

Usage Examples:

{
  "scripts": {
    "prebump": "npm run lint && npm run test",
    "postbump": "npm run build",
    "prechangelog": "echo 'Generating changelog...'",
    "postchangelog": "npm run format-changelog",
    "precommit": "npm run security-check",
    "postcommit": "echo 'Changes committed successfully'",
    "pretag": "npm run validate-tag",
    "posttag": "npm publish && npm run deploy-docs"
  }
}

Step Skipping Configuration

Configure which steps of the release process to skip.

interface SkipConfiguration {
  bump?: boolean;        // Skip version calculation and file updates
  changelog?: boolean;   // Skip changelog generation
  commit?: boolean;      // Skip git commit creation
  tag?: boolean;         // Skip git tag creation
}

Usage Examples:

{
  "skip": {
    "bump": false,
    "changelog": false,
    "commit": false,
    "tag": false
  }
}

Advanced Configuration Options

Extended configuration for complex workflows and integrations.

interface AdvancedConfiguration {
  // Conventional changelog configuration
  preset?: string;                       // Changelog preset name
  header?: string;                       // Custom changelog header
  path?: string;                         // Only include commits under path
  
  // Custom updater configuration
  updaters?: Array<{
    filename: string;
    type?: 'json' | 'plain-text';
    updater?: string | UpdaterObject;
  }>;
  
  // Git configuration
  gitTagFallback?: boolean;              // Fallback to git tags for version
  commitAll?: boolean;                   // Commit all changes, not just version files
}

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

Usage Examples:

{
  "preset": "angular",
  "header": "# Changelog\n\nAll notable changes documented here.\n",
  "path": "packages/core",
  "updaters": [
    {
      "filename": "version.py",
      "type": "plain-text"
    },
    {
      "filename": "Cargo.toml",
      "updater": "./scripts/cargo-updater.js"
    }
  ]
}

Environment Variable Integration

Configuration can be influenced by environment variables in JavaScript config files.

// .versionrc.js
export default {
  silent: process.env.CI === 'true',
  dryRun: process.env.DRY_RUN === 'true',
  tagPrefix: process.env.TAG_PREFIX || 'v',
  scripts: {
    prebump: process.env.SKIP_TESTS === 'true' ? '' : 'npm test',
    posttag: process.env.AUTO_PUBLISH === 'true' ? 'npm publish' : ''
  },
  skip: {
    tag: process.env.SKIP_TAGGING === 'true',
    changelog: process.env.SKIP_CHANGELOG === 'true'
  }
};

Configuration Validation

Standard Version validates configuration format and throws descriptive errors for invalid configurations.

/**
 * Configuration validation rules:
 * - scripts must be an object (not array or primitive)
 * - skip must be an object (not array or primitive)
 * - JavaScript configs must export object or function returning object
 * - Function configs are called with no arguments
 */

Common Validation Errors:

// Invalid configuration examples that will throw errors:

// ❌ scripts as array
{ "scripts": ["prebump", "postbump"] }

// ❌ skip as string  
{ "skip": "changelog,tag" }

// ❌ JavaScript config returning non-object
module.exports = "invalid";

// ✅ Valid configurations
{ "scripts": { "prebump": "npm test" } }
{ "skip": { "changelog": true } }
module.exports = { tagPrefix: "v" };

Configuration Priority

Configuration is loaded and merged in the following order (later sources override earlier ones):

Built-in defaults
Conventional changelog config spec defaults
Configuration file (first found: .versionrc, .versionrc.cjs, .versionrc.json, .versionrc.js)
package.json "standard-version" key
Command-line arguments (CLI only)
Programmatic options (API only)