@sylphx/bump
Advanced tools
Fully semantic release automation. Conventional commits in, semantic versions out.
workspace:* dependencies at publish time| bump | changesets | |
|---|---|---|
| Setup | 1 workflow file | Multiple config files + bot |
| Workflow | Just commit | Create changeset file per change |
| Version control | Automatic from commits | Manual per-changeset |
| Learning curve | Know conventional commits? Done | New syntax + tooling |
| PR noise | 1 release PR | 1 changeset file per change |
| Fine-grained control | Via commit message or bump file | Via changeset file |
| Workspace protocol | Auto-resolved | Manual handling required |
| Cascade bumps | Automatic | Manual configuration |
Both tools support fine-grained version control - the difference is where you express it:
feat: = minor, fix: = patch, feat!: = major), or optionally via bump files for custom changelog entriesChoose bump if you prefer keeping version intent in your git history. Choose changesets if you prefer separate files for release notes.
feat: add login or fix: resolve buggit commit -m "feat: add dark mode"
git push
↓
[Release PR created automatically]
↓
[You merge when ready]
↓
[Published to npm!]
Create .github/workflows/release.yml:
name: Release
on:
push:
branches: [main]
permissions:
contents: write
pull-requests: write
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: SylphxAI/bump@v0
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
npm-token: ${{ secrets.NPM_TOKEN }}
NPM_TOKEN, Value: your tokenPush a commit and watch the magic happen.
Use these prefixes in your commits:
| Commit | Version Bump | Example |
|---|---|---|
feat: | Minor (1.0.0 → 1.1.0) | feat: add dark mode |
fix: | Patch (1.0.0 → 1.0.1) | fix: resolve login bug |
feat!: | Major (1.0.0 → 2.0.0) | feat!: redesign API |
Other prefixes like docs:, chore:, test:, ci: don't trigger releases.
During 0.x development, breaking changes bump minor instead of major (per semver spec):
feat!: on 0.1.0 → 0.2.0 (not 1.0.0)When ready for stable release, create a bump file:
# .bump/graduate.md
---
release: "1.0.0"
---
First stable release!
When you push to main:
┌─────────────────────────────────────────────────────────┐
│ Your commits: │
│ - feat: add user profile │
│ - fix: resolve logout issue │
│ - docs: update readme │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ PR #42: chore(release): 1.2.0 │
├─────────────────────────────────────────────────────────┤
│ ## 🚀 Release │
│ │
│ This PR will release **my-package** version **1.2.0** │
│ │
│ ### ✨ Features │
│ - add user profile (abc1234) │
│ │
│ ### 🐛 Bug Fixes │
│ - resolve logout issue (def5678) │
│ │
│ > Merging this PR will publish to npm │
└─────────────────────────────────────────────────────────┘
↓
[You merge the PR]
↓
[Published to npm! 🚀]
Whenever you want to publish. The PR stays open and updates automatically with each push. Merge it when you're ready to release.
Just don't merge the PR. It will keep updating as you push more commits.
Yes! Use mode: release to publish directly:
- uses: SylphxAI/bump@v0
with:
mode: release
github-token: ${{ secrets.GITHUB_TOKEN }}
npm-token: ${{ secrets.NPM_TOKEN }}
Yes! Add workflow_dispatch:
on:
workflow_dispatch: # Manual trigger
push:
branches: [main]
Then go to Actions → Release → Run workflow.
The CLI is for local development - checking status and creating bump files:
# Install
npm add -D @sylphx/bump
# Check release status (also runs with just `bump`)
bump status
# Create bump files
bump add # Interactive mode
bump add minor # Minor release
bump add patch --beta # Patch with beta prerelease
bump add minor -p @scope/core # Target specific package
bump add "1.0.0" # Explicit version
# Initialize config (optional)
bump init
Note: Releases are handled automatically by GitHub Actions. The CLI is only for local development.
Bump automatically detects monorepos (via workspaces in package.json) and handles them intelligently:
@scope/pkg@1.0.0 format for independent tracking┌────────────────────────────────────────────────────────────┐
│ PR #42: chore(release): @scope/foo@1.2.0, @scope/bar@2.0.0│
├────────────────────────────────────────────────────────────┤
│ ## 🚀 Release │
│ │
│ | Package | Current | New | Type | │
│ |-------------|---------|-------|-------| │
│ | @scope/foo | 1.1.0 | 1.2.0 | minor | │
│ | @scope/bar | 1.9.0 | 2.0.0 | major | │
│ │
│ ### 📦 @scope/foo `1.1.0` → `1.2.0` │
│ - feat: add new feature (abc1234) │
│ │
│ ### 📦 @scope/bar `1.9.0` → `2.0.0` ⚠️ │
│ - feat!: breaking change (def5678) │
└────────────────────────────────────────────────────────────┘
Same workflow as single packages - just make sure you have workspaces in your root package.json:
{
"workspaces": ["packages/*"]
}
No additional configuration needed!
Create bump.config.ts for custom settings:
import { defineConfig } from '@sylphx/bump'
export default defineConfig({
// Customize commit types
conventional: {
types: {
feat: 'minor',
fix: 'patch',
perf: 'patch',
// Add your own
improvement: 'minor',
},
},
// Changelog options
changelog: {
file: 'CHANGELOG.md',
groupBy: 'type', // or 'scope' or 'none'
},
// Publishing options
publish: {
access: 'public',
tag: 'latest', // or 'next', 'beta', etc.
},
})
Use bump files for pre-release versions:
# .bump/beta.md
---
release: minor
prerelease: beta
---
New beta feature.
→ 1.0.0 → 1.1.0-beta.0
Workflow:
.bump/beta.md with prerelease: betav1.1.0-beta.0.bump/stable.md without prereleasev1.1.0While bump works automatically from commits, you can use bump files for:
Use the bump add command:
# Interactive mode - prompts for all options
bump add
# Quick creation
bump add patch # Patch release
bump add minor # Minor release
bump add major # Major release
# With prerelease
bump add minor --alpha # 1.0.0 → 1.1.0-alpha.0
bump add minor --beta # 1.0.0 → 1.1.0-beta.0
bump add minor --rc # 1.0.0 → 1.1.0-rc.0
bump add patch --prerelease next # Custom prerelease tag
# Target specific package (monorepo)
bump add patch -p @scope/core
bump add minor --package @scope/utils
# With changelog message
bump add minor -m "Added new dashboard feature"
# Explicit version (recovery)
bump add "1.2.3" # Set exact version
Or create a markdown file in .bump/ directory manually:
# .bump/feature.md
---
release: minor
---
### New Dashboard
Completely redesigned the analytics dashboard with:
- Real-time data updates
- Customizable widgets
- Export to PDF/CSV
Fields:
release - patch, minor, major, or explicit version "1.2.3"prerelease - (optional) alpha, beta, rcpackage / packages - (optional) target package(s)# .bump/beta-feature.md
---
release: minor
prerelease: beta
---
New feature in beta testing.
→ 1.0.0 → 1.1.0-beta.0
# .bump/rc.md
---
release: patch
prerelease: rc
packages:
- @scope/core
- @scope/utils
---
Release candidate.
→ 1.0.0 → 1.0.1-rc.0
Single package:
---
release: patch
package: @scope/core
---
Bug fix for core module.
Multiple packages:
---
release: minor
packages:
- @scope/core
- @scope/utils
---
Shared feature across packages.
All packages (omit package field):
---
release: patch
---
Security fix for all packages.
.bump/*.md file with frontmatterIf npm publish fails due to a blocked version:
# .bump/recovery.md
---
release: "1.2.1"
package: @scope/mypackage
---
Recovery release after npm publish failure.
Push this file, and bump will create a new PR with version 1.2.1.
| Input | Description | Default |
|---|---|---|
mode | auto, release, version, or pr | auto |
github-token | GitHub token | required |
npm-token | NPM token for publishing | - |
dry-run | Preview without publishing | false |
base-branch | Base branch for PR mode | main |
tag | Create git tags | true |
changelog | Update CHANGELOG.md | true |
github-release | Create GitHub release | true |
The workflow requires these permissions:
permissions:
contents: write # For creating tags and releases
pull-requests: write # For creating/updating release PRs
MIT
FAQs
Modern changelog and release management
The npm package @sylphx/bump receives a total of 15 weekly downloads. As such, @sylphx/bump popularity was classified as not popular.
We found that @sylphx/bump demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
The compromise affects MemTensor's MemOS, an open source memory framework for large language models (LLMs) and AI agents. Both npm package @memtensor/memos-cloud-openclaw-plugin and the PyPI package MemoryOS are compromised. They drop cross-platform Go binaries that exfiltrate developer secrets.
Security News
Lovable’s OJ rewrites Vite’s dev server in Rust, reducing memory use and preview times as AI lowers the cost of open source reimplementation.
Security News
It has been one year since Shai-Hulud made its first appearance on npm.