bump-next-version.js

Overview

bump-next-version.js is a utility script designed to automate the version bumping process of a Node.js project following semantic versioning (semver) conventions. It reads the current version from the project's package.json file, determines the next version based on environment variables specifying the release type (beta or stable) and version increment type (patch, minor, major), and then updates the version using npm version.

This script supports:

• Beta releases with automatic prerelease version increments (e.g., 1.0.0-beta.0, 1.0.0-beta.1, etc.).

• Stable releases with explicit version increments.

• A dry run mode to simulate version bumping without making changes.

• Error handling for invalid inputs or failed version bump commands.

This tool is typically integrated into CI/CD pipelines or release workflows to ensure consistent versioning of the project.

Detailed Explanation

Constants and Dependencies

• fs: Used to read the package.json file.

• path: Helps resolve the path to package.json.

• child_process.execSync: Executes shell commands synchronously.

• semver: A library to handle semantic version parsing and incrementing.

Variables

• packageJsonPath: Absolute path to the package.json file (one directory above the script).

• packageJsonData: Raw JSON string read from package.json.

• packageJson: Parsed JSON object of package.json.

• version: Current version string extracted from packageJson.

• releaseType: Environment variable RELEASE_TYPE, defaults to 'beta'.

• semverType: Environment variable SEMVER_TYPE, expected to be one of 'patch', 'minor', or 'major' for stable releases.

Function: bumpVersion(version)

Purpose

Executes the version bump command using npm version <version>. Can run in dry-run mode where it only prints the command instead of executing it.

Parameters

• version (string): The new version string to set using npm version.

Returns

• None (void). The function either executes the version bump or logs the dry run command. If an error occurs during execution, the process exits with an error code.

Implementation Details

• Checks if the environment variable DRY_RUN is set.

• If dry run, logs the command to the console.

• Otherwise, runs the command synchronously and inherits stdio to show command output.

• On failure, logs the error and exits with code 1.

Usage Example

bumpVersion('1.0.1-beta.2');
// Executes: npm version 1.0.1-beta.2 or logs the command if DRY_RUN is set

Version Calculation Logic

1. Beta Release (releaseType === 'beta')

   • If the current version is already a prerelease (e.g., 1.0.0-beta.1), increment the prerelease number (e.g., to 1.0.0-beta.2).

   • Otherwise, create a new prerelease version with the identifier 'beta' and the semverType (e.g., prepatch, preminor, or premajor).

   • The semverType environment variable influences the type of prerelease bump (patch, minor, or major).

2. Stable Release (releaseType === 'stable')

   • Requires a valid semverType (one of patch, minor, or major).

   • Increments the version accordingly (e.g., from 1.0.0 to 1.0.1 for patch).

   • If semverType is missing or invalid, logs an error and exits.

3. Invalid releaseType

   • Logs an error and exits.

After determining the new version, calls bumpVersion to update the version.

Interaction with Other Parts of the System

• package.json: Reads and updates the version inside this file via npm version.

• Environment Variables:

  • RELEASE_TYPE: Controls whether this is a beta or stable release.

  • SEMVER_TYPE: Controls the kind of version increment (patch, minor, major).

  • DRY_RUN: If set, prevents actual version bump and outputs the intended command.

• npm: Uses npm's versioning command to update package.json and create git tags if applicable.

• Typically invoked during release automation scripts or CI/CD pipelines.

Important Implementation Details

• Uses the semver library to safely parse and increment versions according to semver rules.

• Supports prerelease versioning by handling "beta" tags and numeric increments.

• Gracefully handles errors with exit codes and descriptive console messages.

• Sync execution (execSync) ensures the script waits for the version bump command to complete before proceeding.

• Decouples version calculation logic from the actual command execution.

Visual Diagram

The following flowchart illustrates the decision-making flow and function calls within bump-next-version.js:

flowchart TD
    Start([Start])
    ReadPkgJson[Read package.json version]
    GetEnvVars[Fetch RELEASE_TYPE and SEMVER_TYPE]
    DetermineReleaseType{RELEASE_TYPE?}
    BetaRelease[Beta Release Logic]
    StableRelease[Stable Release Logic]
    InvalidReleaseType[Error: Invalid RELEASE_TYPE]
    CalcNewVersion[Calculate New Version]
    bumpVersionCall[bumpVersion(newVersion)]
    DryRunCheck{DRY_RUN?}
    LogCommand[Log "npm version <newVersion>"]
    ExecNpmCmd[Execute "npm version <newVersion>"]
    ErrorHandling[On exec error: log + exit(1)]
    End([End])

    Start --> ReadPkgJson --> GetEnvVars --> DetermineReleaseType
    DetermineReleaseType -->|beta| BetaRelease
    DetermineReleaseType -->|stable| StableRelease
    DetermineReleaseType -->|other| InvalidReleaseType --> End

    BetaRelease --> CalcNewVersion
    StableRelease --> CalcNewVersion

    CalcNewVersion --> bumpVersionCall
    bumpVersionCall --> DryRunCheck
    DryRunCheck -->|true| LogCommand --> End
    DryRunCheck -->|false| ExecNpmCmd --> End
    ExecNpmCmd -->|error| ErrorHandling --> End

Summary

bump-next-version.js is a focused utility script that automates version bumping in a Node.js project by reading the current version, calculating the next version based on release and semver types, and executing the appropriate npm version command. It provides support for beta prerelease versions, stable releases, dry-run mode, and robust error handling, making it ideal for integration in automated release workflows.