CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-bumpp

Automated version bumping tool with git integration for semantic versioning workflows

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

configuration.mddocs/

Configuration

Configuration system supporting file-based configuration, environment overrides, and programmatic configuration with type-safe defaults and automatic discovery.

Capabilities

Define Config Helper

Helper function for creating type-safe configuration objects in config files.

/**
 * Helper function for defining bumpp configuration with full type safety
 * @param config - Partial configuration object
 * @returns The same configuration object (provides TypeScript IntelliSense)
 */
function defineConfig(config: Partial<VersionBumpOptions>): Partial<VersionBumpOptions>;

Usage Examples:

Create a bump.config.ts file:

import { defineConfig } from "bumpp";

export default defineConfig({
  commit: "chore: release v%s",
  tag: "v%s",
  push: true,
  sign: true,
  files: [
    "package.json",
    "src/version.ts",
    "README.md"
  ],
  execute: "npm run build && npm test"
});

Create a bump.config.js file:

const { defineConfig } = require("bumpp");

module.exports = defineConfig({
  recursive: true,
  commit: true,
  tag: true,
  push: false, // Don't auto-push in CI
  printCommits: true
});

Load Configuration

Loads and merges configuration from files, defaults, and runtime overrides.

/**
 * Loads configuration from config files with optional overrides
 * @param overrides - Runtime configuration overrides
 * @param cwd - Working directory to search for config files
 * @returns Promise resolving to merged configuration
 */
function loadBumpConfig(
  overrides?: Partial<VersionBumpOptions>,
  cwd?: string
): Promise<VersionBumpOptions>;

Usage Examples:

import { loadBumpConfig } from "bumpp";

// Load default configuration
const config = await loadBumpConfig();

// Load with runtime overrides
const config = await loadBumpConfig({
  release: "patch",
  push: false
});

// Load from specific directory
const config = await loadBumpConfig({}, "/path/to/project");

Configuration Defaults

Default configuration values applied when no config file is present.

/**
 * Default configuration values for version bump operations
 */
const bumpConfigDefaults: VersionBumpOptions;

Default Values:

const bumpConfigDefaults = {
  commit: true,           // Create git commits
  push: true,             // Push to remote
  tag: true,              // Create git tags
  sign: false,            // Don't sign by default
  install: false,         // Don't run install
  recursive: false,       // Single package mode
  noVerify: false,        // Run git hooks
  confirm: true,          // Prompt for confirmation
  ignoreScripts: false,   // Run npm scripts
  all: false,             // Don't include all files in commit
  noGitCheck: true,       // Skip git status check
  files: []               // Use auto-detected files
};

Configuration File Discovery

Supported Config Files

bumpp automatically searches for configuration files in this order:

  1. bump.config.js
  2. bump.config.mjs
  3. bump.config.ts
  4. bump.config.mts
  5. bump.config.json

Search Behavior

Configuration file search:

  • Starts from current working directory
  • Searches up the directory tree
  • Stops at git repository root (.git directory)
  • Uses first config file found

Config File Formats

TypeScript Configuration:

// bump.config.ts
import { defineConfig } from "bumpp";

export default defineConfig({
  release: "patch",
  commit: "feat: update version to %s",
  tag: "release-%s",
  files: ["package.json", "version.json"],
  execute: async () => {
    // Custom pre-commit logic
    console.log("Running pre-commit tasks...");
  }
});

JavaScript Configuration:

// bump.config.js
const { defineConfig } = require("bumpp");

module.exports = defineConfig({
  recursive: true,
  commit: true,
  tag: true,
  push: process.env.CI !== "true", // Don't push in CI
  printCommits: 5
});

JSON Configuration:

{
  "commit": "chore: bump version",
  "tag": "v%s",
  "push": true,
  "files": [
    "package.json",
    "src/constants.ts"
  ]
}

Configuration Options Reference

Version Options

interface VersionBumpOptions {
  /** Version string or release type to bump to */
  release?: string;
  /** Current version (auto-detected if not provided) */
  currentVersion?: string;
  /** Prerelease identifier (alpha, beta, rc, etc.) */
  preid?: string;
  /** Custom version provider function */
  customVersion?: (currentVersion: string, semver: typeof import('semver')) => Promise<string | void> | string | void;
}

Git Integration Options

interface VersionBumpOptions {
  /** Create git commit (boolean or custom message) */
  commit?: boolean | string;
  /** Create git tag (boolean or custom format) */
  tag?: boolean | string;
  /** Sign git commit and tag */
  sign?: boolean;
  /** Push commit and tag to remote */
  push?: boolean;
  /** Include all files in commit (--all flag) */
  all?: boolean;
  /** Skip git working directory check */
  noGitCheck?: boolean;
  /** Bypass git hooks (--no-verify flag) */
  noVerify?: boolean;
}

File Management Options

interface VersionBumpOptions {
  /** Files to update with new version */
  files?: string[];
  /** Working directory for operations */
  cwd?: string;
  /** Enable recursive bumping for monorepos */
  recursive?: boolean;
}

Execution Options

interface VersionBumpOptions {
  /** Run npm install after version bump */
  install?: boolean;
  /** Skip npm lifecycle scripts */
  ignoreScripts?: boolean;
  /** Custom command or function to execute before commit */
  execute?: string | ((config: Operation) => void | PromiseLike<void>);
}

Interface Options

interface VersionBumpOptions {
  /** Prompt for confirmation before execution */
  confirm?: boolean;
  /** CLI interface configuration */
  interface?: boolean | InterfaceOptions;
  /** Progress callback for operation updates */
  progress?: (progress: VersionBumpProgress) => void;
  /** Print recent commit history */
  printCommits?: boolean;
}

interface InterfaceOptions {
  /** Input stream for CLI prompts */
  input?: NodeJS.ReadableStream | NodeJS.ReadStream | boolean;
  /** Output stream for CLI output */
  output?: NodeJS.WritableStream | NodeJS.WriteStream | boolean;
  /** Additional readline options */
  [key: string]: unknown;
}

Configuration Merging

Precedence Order

Configuration is merged in this order (later values override earlier):

  1. Default values (bumpConfigDefaults)
  2. Configuration file (bump.config.*)
  3. Runtime overrides (passed to loadBumpConfig() or versionBump())

Example Configuration Merging

// bump.config.ts
export default defineConfig({
  commit: "chore: version %s",
  tag: true,
  push: true,
  files: ["package.json"]
});

// Runtime usage
const result = await versionBump({
  release: "patch",    // Added at runtime
  push: false,         // Overrides config file
  tag: "v%s"          // Overrides config file
});

// Final merged config:
// {
//   commit: "chore: version %s",  // From config file
//   tag: "v%s",                   // Runtime override
//   push: false,                  // Runtime override
//   release: "patch",             // Runtime addition
//   files: ["package.json"],      // From config file
//   // ... plus all defaults
// }

Environment-Specific Configuration

Conditional Configuration

Create environment-aware configuration:

// bump.config.ts
import { defineConfig } from "bumpp";

const isProd = process.env.NODE_ENV === "production";
const isCI = process.env.CI === "true";

export default defineConfig({
  commit: isProd ? "release: v%s" : "chore: bump to %s",
  push: !isCI,  // Don't auto-push in CI environments
  sign: isProd, // Only sign production releases
  execute: isProd ? "npm run build && npm test" : undefined
});

CI/CD Integration

Example CI-friendly configuration:

// bump.config.ts
import { defineConfig } from "bumpp";

export default defineConfig({
  commit: "chore(release): %s",
  tag: "v%s",
  push: false,              // Let CI handle pushing
  noGitCheck: true,         // Skip dirty check in CI
  confirm: false,           // No interactive prompts
  printCommits: false,      // Reduce CI noise
  execute: "npm run build"  // Build before commit
});

Advanced Configuration Patterns

Monorepo Configuration

Configuration for workspace/monorepo projects:

// bump.config.ts
import { defineConfig } from "bumpp";

export default defineConfig({
  recursive: true,
  commit: "chore: bump all packages to %s",
  tag: "release-%s",
  execute: async (operation) => {
    // Custom monorepo build process
    console.log(`Building all packages for ${operation.state.newVersion}`);
    await runCommand("npm run build:all");
    await runCommand("npm run test:all");
  }
});

Project-Specific File Updates

Update project-specific files with version numbers:

// bump.config.ts
import { defineConfig } from "bumpp";

export default defineConfig({
  files: [
    "package.json",              // NPM manifest
    "Cargo.toml",               // Rust manifest
    "pyproject.toml",           // Python project
    "src/version.ts",           // Version constant
    "README.md",                // Documentation
    "docker-compose.yml",       // Docker services
    "helm/Chart.yaml",          // Kubernetes Helm chart
    "docs/api-reference.md"     // API documentation
  ],
  execute: "npm run docs:build" // Rebuild docs with new version
});

Custom Version Provider

Implement custom version calculation logic:

// bump.config.ts
import { defineConfig } from "bumpp";
import semver from "semver";

export default defineConfig({
  customVersion: async (currentVersion, semverLib) => {
    // Custom logic for next version
    const parsed = semverLib.parse(currentVersion);
    if (!parsed) return;
    
    // Example: Always bump patch and add build metadata
    const nextPatch = semverLib.inc(currentVersion, "patch");
    const buildNumber = await getBuildNumber();
    return `${nextPatch}+build.${buildNumber}`;
  }
});

Install with Tessl CLI

npx tessl i tessl/npm-bumpp

docs

cli-interface.md

configuration.md

index.md

release-types.md

version-bumping.md

tile.json