Installation

CLI setup

The primary way to use beachball is by installing it as a devDependency and configuring wrapper scripts. (You can also run beachball via npx.)

Note

In a monorepo, beachball should be installed at and run from the repo root only.

Automatic setup

Run npx beachball init to automatically run the steps outlined below.

Warning

This will install beachball v2. To use v3, follow the manual steps.

Manual setup

Note

While beachball v3 is in prerelease, you should get the latest version with npm show beachball@next version and then install a specific pinned version, instead of the latest version as shown below. See the migration guide for more details.

To get started, install beachball as a devDependency:

npm install -D beachball

or for yarn users:

yarn add -D beachball

After that, add some scripts to call beachball commands:

{
  "scripts": {
    "change": "beachball change",
    "checkchange": "beachball check",
    "release": "beachball publish"
  }
}

You should also ensure that a repository URL is set in your repo root package.json to help beachball figure out which remote to compare against when determining changes. For example:

{
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org-name/your-repo-name.git"
  }
}

Local development workflow

After making and committing changes in a branch, run npm run change or yarn change to generate change files. See the change files page for more details.

CI integration

There are two parts to CI integration with beachball:

  1. Add a PR build step to call beachball check to validate that change files are included.
  2. Add a release build step to call beachball publish to publish to npm and push back to git.
Last Updated: