# 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.

# Manual setup

To get started, install beachball as a devDependency:

npm install -D beachball

or for yarn users (add -W if in a monorepo):

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 (opens new window) 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.