@stacksjs/bumpx

bumpx

A powerful, modern version bumping tool with comprehensive Git integration, workspace detection, and monorepo support.

Features

• 🚀 Zero dependencies - Built using only Node.js built-ins and Bun tooling
• 📦 Semver compliant - Supports all semantic versioning release types
• 🔄 Workspace detection - Automatic workspace/monorepo detection with recursive enabled by default
• 🎯 Git integration - Automatic commit, tag, and push (all enabled by default)
• ⚡ Fast execution - Compiled binary for instant startup
• 🛠 Highly configurable - Config file and CLI options
• 🎨 Interactive prompts - Choose version increment interactively
• 🔧 Custom commands - Execute scripts before git operations
• 📝 Changelog generation - Automatic changelog generation enabled by default
• 🌐 Cross-platform - Works seamlessly on macOS, Linux, and Windows

Installation

# Install globally
bun install -g @stacksjs/bumpx

# Or use with bunx
bunx @stacksjs/bumpx patch

Usage

Basic Usage

# Bump patch version (1.0.0 → 1.0.1)
bumpx patch

# Bump minor version (1.0.0 → 1.1.0)
bumpx minor

# Bump major version (1.0.0 → 2.0.0)
bumpx major

# Bump to specific version
bumpx 1.2.3

# Interactive version selection
bumpx prompt

Prerelease Versions

# Bump to prerelease
bumpx prepatch --preid beta  # 1.0.0 → 1.0.1-beta.0
bumpx preminor --preid alpha # 1.0.0 → 1.1.0-alpha.0
bumpx premajor --preid rc    # 1.0.0 → 2.0.0-rc.0

# Increment prerelease
bumpx prerelease  # 1.0.1-beta.0 → 1.0.1-beta.1

Git Integration

# Default behavior: commit, tag, and push (all enabled by default)
bumpx patch

# Disable specific git operations
bumpx patch --no-commit --no-tag --no-push

# Custom commit message
bumpx patch --commit-message "chore: release v{version}"

# Custom tag message
bumpx patch --tag-message "Release v{version}"

# Sign commits and tags
bumpx patch --sign

# Skip git hooks
bumpx patch --no-verify

Workspace & Monorepo Support

# Automatic workspace detection (recursive is default)
bumpx patch

# Explicitly disable recursive mode
bumpx patch --no-recursive

# Bump specific files
bumpx patch --files package.json,packages/*/package.json

Advanced Options

# Execute custom commands
bumpx patch --execute "bun run build" --execute "bun test"

# Install dependencies after bump
bumpx patch --install

# Skip confirmation prompts
bumpx patch --yes

# CI mode (non-interactive, quiet)
bumpx patch --ci

# Print recent commits
bumpx patch --print-commits

# Skip git status check
bumpx patch --no-git-check

# Generate changelog (enabled by default)
bumpx patch --changelog

# Disable changelog generation
bumpx patch --no-changelog

# Dry run to preview changes
bumpx patch --dry-run

CI/CD Integration

bumpx is designed to work seamlessly in CI/CD environments:

Quick CI Usage

# CI mode - automatically non-interactive
bumpx patch --ci

# Or with explicit flags
bumpx patch --yes --quiet

# Auto-detect CI environment
export CI=true
bumpx patch  # Automatically enables CI mode

GitHub Actions Example

name: Release
on:
  workflow_dispatch:
    inputs:
      release_type:
        description: Release type
        required: true
        default: patch
        type: choice
        options: [patch, minor, major]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0

      - uses: oven-sh/setup-bun@v1

      - name: Install dependencies
        run: bun install

      - name: Configure git
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"

      - name: Version bump and release
        run: bunx bumpx ${{ github.event.inputs.release_type }} --ci

For more CI/CD examples and configurations, see Automation Guide.

Configuration

Create a bumpx.config.ts file in your project root:

import { defineConfig } from '@stacksjs/bumpx'

export default defineConfig({
  // Git options (these are the defaults)
  commit: true,
  tag: true,
  push: true,
  sign: false,

  // Execution options
  install: false,
  execute: ['bun run build', 'bun run test'],

  // UI options
  confirm: true,
  quiet: false,

  // Advanced options
  recursive: true, // Default is now true with workspace detection
  printCommits: true,
  changelog: true, // Changelog generation enabled by default
  respectGitignore: true
})

You can also use JSON configuration in package.json:

{
  "bumpx": {
    "commit": true,
    "tag": true,
    "push": true,
    "execute": ["bun run build"]
  }
}

CLI Options

Option	Alias	Description	Default
--preid		ID for prerelease
--all		Include all files	false
--no-git-check		Skip git status check
--commit [msg]	-c	Create git commit	true
--no-commit		Skip git commit
--tag [name]	-t	Create git tag	true
--no-tag		Skip git tag
--push	-p	Push to remote	true
--no-push		Skip git push
--sign		Sign commits and tags	false
--install		Run npm install	false
--execute	-x	Execute command
--recursive	-r	Bump recursively	true
--yes	-y	Skip confirmation	false
--quiet	-q	Quiet mode	false
--ci		CI mode (sets --yes --quiet)	false
--no-verify		Skip git hooks	false
--ignore-scripts		Ignore npm scripts	false
--current-version		Override current version
--print-commits		Show recent commits	false

Library Usage

You can also use bumpx programmatically:

import { versionBump } from '@stacksjs/bumpx'

await versionBump({
  release: 'patch',
  commit: true,
  tag: true,
  push: true,
  progress: ({ event, newVersion }) => {
    console.log(`${event}: ${newVersion}`)
  }
})

Changelog

Please see our releases page for information on changes.

Contributing

Please see CONTRIBUTING for details.

Community

For help or discussion:

• Discussions on GitHub
• Join the Stacks Discord Server

Postcardware

“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Credits

• version-bump-prompt - for the initial inspiration
• Antony Fu - for creating bumpp
• Chris Breuer
• All Contributors

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙