Configuration

bumpx offers flexible configuration options to customize its behavior for your project and team's workflow.

Configuration Files

Project Configuration

Create a configuration file in your project root for project-specific defaults. bumpx supports multiple configuration file formats:

TypeScript/JavaScript configuration files:

// bumpx.config.ts
export default {
  commit: true,
  tag: true,
  push: false,
  sign: true,
  message: 'chore: release v%s',
  tagMessage: 'Release v%s',
  files: ['package.json', 'package-lock.json'],
  preid: 'alpha',
  noGitCheck: false,
  noVerify: false,
  recursive: false,
  install: false,
  execute: ''
}

// bumpx.config.js
module.exports = {
  commit: true,
  tag: true,
  push: false,
  sign: true,
  message: 'chore: release v%s',
  tagMessage: 'Release v%s',
  files: ['package.json', 'package-lock.json'],
  preid: 'alpha',
  noGitCheck: false,
  noVerify: false,
  recursive: false,
  install: false,
  execute: ''
}

Package.json configuration:

{
  "name": "my-project",
  "version": "1.0.0",
  "bumpx": {
    "commit": true,
    "tag": true,
    "push": false,
    "sign": true,
    "message": "chore: release v%s",
    "tagMessage": "Release v%s",
    "files": ["package.json", "package-lock.json"],
    "preid": "alpha"
  }
}

Alternative config directory locations:

# In .config directory
.config/bumpx.ts
.config/bumpx.js
.config/bumpx.mjs
.config/bumpx.cjs

# In config directory
config/bumpx.ts
config/bumpx.js
config/bumpx.mjs
config/bumpx.cjs

Global Configuration

Create a global configuration in your home directory:

// ~/.config/bumpx.config.ts
export default {
  sign: true,
  push: false,
  verbose: true,
  message: 'chore: bump version to %s',
  tagMessage: 'v%s'
}

Or in package.json within a global npm project:

{
  "bumpx": {
    "sign": true,
    "push": false,
    "verbose": true,
    "message": "chore: bump version to %s",
    "tagMessage": "v%s"
  }
}

Configuration Priority

Configuration is applied in this order (later options override earlier ones):

1. Global configuration (~/.config/bumpx.config.* or global package.json)
2. Project configuration (local config files or package.json)
3. Command line arguments
4. Environment variables

Supported Configuration File Names

bumpx looks for configuration files in this order:

1. bumpx.config.ts
2. bumpx.config.js
3. bumpx.config.mjs
4. bumpx.config.cjs
5. .config/bumpx.config.ts
6. .config/bumpx.config.js
7. .config/bumpx.config.mjs
8. .config/bumpx.config.cjs
9. config/bumpx.config.ts
10. config/bumpx.config.js
11. config/bumpx.config.mjs
12. config/bumpx.config.cjs
13. package.json (bumpx key)

Configuration Options

Version Control

commit (boolean)

• Default: false
• Description: Automatically create a git commit after version bump
• CLI: --commit / --no-commit

{
  "commit": true
}

tag (boolean)

• Default: false
• Description: Create a git tag after version bump
• CLI: --tag / --no-tag

{
  "tag": true
}

push (boolean)

• Default: false
• Description: Push commits and tags to remote repository
• CLI: --push / --no-push

{
  "push": true
}

sign (boolean)

• Default: false
• Description: Sign git commits and tags with GPG
• CLI: --sign / --no-sign

{
  "sign": true
}

Messages

message (string)

• Default: "chore: bump version to %s"
• Description: Git commit message template (use %s for version)
• CLI: --message

{
  "message": "release: v%s"
}

tagMessage (string)

• Default: "v%s"
• Description: Git tag message template (use %s for version)
• CLI: --tag-message

{
  "tagMessage": "Release version %s"
}

File Operations

files (string[])

• Default: ["package.json"]
• Description: List of files to update with new version
• CLI: --files

{
  "files": [
    "package.json",
    "package-lock.json",
    "VERSION.txt",
    "src/version.ts"
  ]
}

recursive (boolean)

• Default: false
• Description: Search for package.json files in subdirectories
• CLI: --recursive / --no-recursive

{
  "recursive": true
}

Version Configuration

preid (string)

• Default: "alpha"
• Description: Prerelease identifier for prerelease versions
• CLI: --preid

{
  "preid": "beta"
}

currentVersion (string)

• Default: Auto-detected from files
• Description: Override the current version for all files
• CLI: --current-version

{
  "currentVersion": "1.0.0"
}

Git Behavior

noGitCheck (boolean)

• Default: false
• Description: Skip git status check (allows dirty working directory)
• CLI: --no-git-check

{
  "noGitCheck": true
}

noVerify (boolean)

• Default: false
• Description: Skip git hooks when committing
• CLI: --no-verify

{
  "noVerify": true
}

Post-Bump Actions

install (boolean)

• Default: false
• Description: Run npm install after version bump
• CLI: --install / --no-install

{
  "install": true
}

execute (string)

• Default: ""
• Description: Command to run after version bump
• CLI: --execute

{
  "execute": "bun run build && bun run test"
}

Output Control

verbose (boolean)

• Default: false
• Description: Enable verbose output
• CLI: --verbose / --quiet

{
  "verbose": true
}

dryRun (boolean)

• Default: false
• Description: Show what would be done without making changes
• CLI: --dry-run

{
  "dryRun": true
}

Environment Variables

You can also configure bumpx using environment variables:

# Set default behavior via environment variables
export BUMPX_COMMIT=true
export BUMPX_TAG=true
export BUMPX_PUSH=false
export BUMPX_SIGN=true
export BUMPX_MESSAGE="chore: release v%s"
export BUMPX_VERBOSE=true

Configuration Examples

Basic Release Workflow

For a simple release workflow with automatic git operations:

{
  "commit": true,
  "tag": true,
  "push": true,
  "message": "chore: release v%s",
  "tagMessage": "Release v%s"
}

Monorepo Configuration

For managing multiple packages in a monorepo:

{
  "recursive": true,
  "commit": true,
  "tag": true,
  "message": "chore: bump all packages to v%s",
  "files": [
    "package.json",
    "packages/*/package.json"
  ]
}

CI/CD Integration

For automated releases in CI environments:

{
  "commit": true,
  "tag": true,
  "push": true,
  "noVerify": true,
  "execute": "bun run build && bun run test:ci",
  "message": "chore(release): v%s [skip ci]"
}

Development Workflow

For development with prerelease versions:

{
  "preid": "dev",
  "commit": true,
  "tag": false,
  "push": false,
  "message": "chore: dev release v%s"
}

Security-Focused

For projects requiring signed commits:

{
  "sign": true,
  "commit": true,
  "tag": true,
  "noGitCheck": false,
  "noVerify": false,
  "message": "chore: secure release v%s",
  "tagMessage": "Signed release v%s"
}

Advanced Configuration

Custom File Patterns

Support for complex file patterns:

{
  "files": [
    "package.json",
    "apps/*/package.json",
    "libs/*/package.json",
    "VERSION",
    "src/constants/version.ts",
    "docs/package.json"
  ]
}

Conditional Configuration

Use different configurations for different scenarios:

# Development releases
bumpx prerelease --config bumpx.config.dev.ts

# Production releases
bumpx minor --config bumpx.config.prod.ts

# Hotfix releases
bumpx patch --config bumpx.config.hotfix.ts

Team Configuration

Share configuration across your team by committing configuration files:

// bumpx.config.ts - committed to version control
export default {
  commit: true,
  tag: true,
  push: false,
  sign: false,
  message: 'chore: release v%s',
  files: [
    'package.json',
    'package-lock.json'
  ],
  execute: 'bun run build && bun run test'
}

Migration from Other Tools

From npm version

If you're coming from npm version, this configuration provides similar behavior:

{
  "commit": true,
  "tag": true,
  "push": false,
  "message": "v%s",
  "tagMessage": "v%s"
}

From bumpp

For users migrating from bumpp:

{
  "commit": true,
  "tag": true,
  "push": true,
  "execute": "bun run build",
  "message": "chore: release v%s"
}

Validation

bumpx validates your configuration and will warn about:

• Invalid option combinations
• Malformed message templates
• Inaccessible file patterns
• Git configuration issues

To validate your configuration:

# Test configuration without making changes
bumpx patch --dry-run --verbose

Best Practices

1. Start Simple: Begin with basic options and add complexity as needed
2. Use Project Config: Commit configuration files to share team standards
3. Document Changes: Use clear commit messages that explain the release
4. Test First: Always use --dry-run when testing new configurations
5. Secure Releases: Enable signing for production releases
6. Automate Safely: Use --no-verify carefully in CI environments

Troubleshooting

Common Configuration Issues

Config not loading:

# Check config file syntax (for TypeScript/JavaScript files)
npx tsc --noEmit bumpx.config.ts

# Use explicit config file
bumpx patch --config ./my-config.ts

Git operations failing:

# Check git configuration
git config --list | grep user
git config --list | grep signing

# Test git operations manually
git commit --allow-empty -m "test commit"

File patterns not working:

# Test file patterns
ls -la package.json packages/*/package.json

# Use verbose mode to see file resolution
bumpx patch --dry-run --verbose