Getting Started

rivet (short for oxrelease) is a Rust-powered release management CLI for JavaScript/TypeScript monorepos. It handles version bumps, changelogs, internal dependency updates, pre-release versions, and npm publishing.

Install from npm

Install rivet as a dev dependency in your project:

npm install @bdbchgg/rivet --save-dev

Or with pnpm:

pnpm add @bdbchgg/rivet --save-dev

Or with yarn:

yarn add @bdbchgg/rivet --dev

Add to package.json

Add rivet commands to your package.json scripts for convenience:

{
  "scripts": {
    "rivet": "rivet",
    "changeset": "rivet new",
    "bump": "rivet bump",
    "release": "rivet release"
  }
}

Now you can run npm run rivet (or pnpm rivet) instead of npx rivet.

Once installed, verify it works:

npx rivet --help

Initialize

rivet init

This starts an interactive wizard that sets up your project step by step:

1. Release directory — where release files are stored (default: .rivet)
2. Changelog preferences — per-package, global, or none
3. Base branch — usually main
4. Internal dependency strategy — when to update cross-package versions
5. npm access — public or restricted
6. Cargo.toml sync — whether to bump Rust crate versions alongside npm packages
7. Linked groups — packages that share the same bump type
8. Fixed groups — packages that always share the same version

The wizard creates .rivet/config.json with your settings.

You can also skip the wizard:

rivet init --non-interactive

Create a release file

# Interactive — select packages, choose bump type, write summary
rivet new

# Non-interactive
rivet new --package @scope/core:patch --summary "Fix transaction mapping bug"

# Multiple packages
rivet new \
  --package @scope/core:patch \
  --package @scope/react:minor \
  --summary "Improve editor behavior"

This creates a markdown release file in .rivet/ with a descriptive name like a3f2-calm-fox.md.

Preview and bump

# See pending release files and calculated bumps
rivet status

# Preview what would happen
rivet bump --dry-run

# Apply version bumps, update deps, generate changelogs
rivet bump

The bump command:

1. Reads and validates all pending release files
2. Merges bump types (major > minor > patch)
3. Resolves fixed and linked group constraints
4. Applies pre-release tags if configured
5. Updates all package.json versions
6. Updates internal dependency ranges
7. Generates changelogs
8. Saves a release plan for the next step

If anything fails, nothing is written.

Publish

# Publish all bumped packages to npm
rivet release

# Preview without publishing
rivet release --dry-run

# Publish with a custom dist-tag
rivet release --tag next

rivet handles the details:

• Skips private packages
• Checks if a version already exists on the registry before publishing
• Reads publishConfig.access and publishConfig.registry from each package's package.json
• Uses the right dist-tag (pre-release tag, --tag override, or latest)

Full workflow example

# Install
npm install @bdbchgg/rivet --save-dev

# Initialize
rivet init

# Record changes
rivet new --package @scope/core:patch --summary "Fix transaction mapping bug"

# Preview
rivet status
rivet bump --dry-run

# Apply
rivet bump

# Publish
rivet release

Requirements

• Node.js 18+ project with package.json
• npm, pnpm, or yarn for publishing
• A Git repository (for changelog integration)

GitHub Action

For automated version pull requests and publishing, see the Rivet GitHub Action guide.