This documentation applies to beachball v3 prerelease (beachball@next). View the beachball v2 documentation or read the v3 migration guide.

Configuration

For most uses you probably do not need any specific configuration on each package within your repository. But there are a few options to customize beachball's behavior.

There are two types of configurations:

repository config
package config

Repository config

Most often, Beachball config is stored in beachball.config.js, but Beachball will check all the following locations under the project root directory (usually the repo root):

"beachball" key inside package.json
beachball.config.[cm]?[jt]s
.beachballrc (JSON) or .beachballrc.json
.beachballrc.[cm]?[jt]s
any of the above (except package.json) under a .config directory

⚠️ Beachball v3 changed the search order and removed support for YAML files and searching up from the project root to find the config file.

The beachball.config.js example below uses JSDoc type annotations to enable intellisense in some editors (these are optional).

// @ts-check
/** @type {import('beachball').BeachballConfig} */
const config = {
  disallowedChangeTypes: ['major'],
  changehint: 'Run "yarn change" to generate a change file',
  groupChanges: true,
};
module.exports = config;

Package config

Package-level configuration is currently only supported under the beachball key in package.json.

For example, suppose the repo config above is at beachball.config.js at the repo root, and there are these other files:

packages/
  foo/
    package.json
  bar/
    package.json
beachball.config.js
package.json

To change the disallowedChangeTypes for package foo, you could add the following to packages/foo/package.json:

{
  "name": "foo",
  "version": "1.0.0",
  "beachball": {
    "disallowedChangeTypes": null
  }
}

Options

For the latest full list of supported options, see the RepoOptions source.

"Applies to" indicates where the settings can be specified: repo-level config or package-level config.

Option	Type	Default	Applies to	Description
`access`	`'public'` or `'restricted'`	as configured for npm	repo	Publish access level for scoped package names (e.g. `@foo/bar`) - should almost always be `'public'`
`branch`	`string`	see notes	repo	Target branch; see notes
`bumpDeps`	`boolean`	`true`	repo	Bump dependent packages during publish (if B is bumped, and A depends on B, also bump A)
`changeFile`	`ChangeFileOptions`		repo	Customize change files, including the prompt and whether to include the git email
`changehint`	`string`		repo	Hint message for when change files are not detected but required
`changeDir`	`string`	`change`	repo	Directory where change files are stored (relative to repo root)
`changelog`	`ChangelogOptions`		repo	Changelog rendering and grouping options
`commitMessage`	`(options, packageInfos, bumpInfo?) => string`		repo	Customize the commit message for the `change` and `publish` commands. For `publish`, this is overridden by the `--message` CLI option (or `message` config value), and receives the post-bump `packageInfos` and `bumpInfo`.
`concurrency`	`number`	1	repo	Maximum concurrency for write operations, such as npm publish and hook calls, respecting topological order (see also `npmReadConcurrency`)
`defaultNpmTag`	`string`	`'latest'`	repo, package	The default `dist-tag` used for NPM publish
`disallowedChangeTypes`	`string[]`		repo, package	What change types are disallowed
`fetch`	`boolean`	`true`	repo	Fetch from remote before doing diff comparisons
`generateChangelog`	`boolean \| 'md' \| 'json'`	`'md'`	repo	Whether to generate `CHANGELOG.md/json` (`'md'` or `'json'` to generate only that type)
`getGitTag`	`(pkg, defaultTag) => string \| string[] \| null`		repo	Get package-specific git tag(s); return `null` to skip tagging a package
`gitTags`	`boolean`	`true`	repo, package	Whether to create git tags for published packages (eg: `foo_v1.0.1`). Note that `getGitTag` is still respected, overriding this option on a per-package basis.
`groups`	`VersionGroupOptions[]`		repo	Bump these packages together (see details)
`groupChanges`	`boolean`	`false`	repo	Write multiple changes to a single change file
`hooks`	`HooksOptions`		repo	Hooks for custom pre/post publish actions
`ignorePatterns`	`string[]`		repo	Ignore changes in files matching these glob patterns (see notes)
`npmReadConcurrency`	number	5	repo	Maximum concurrency for fetching package versions from the registry (see `concurrency` for write operations)
`package`	`string`		repo	Specifies which package the command relates to (overrides change detection based on `git diff`)
`prereleasePrefix`	`string`		repo	Prerelease prefix, e.g. `"beta"`. Note that if this is specified, packages with change type major/minor/patch will be bumped as prerelease instead.
`packToPath`	`string`		repo	Instead of publishing to npm, pack packages to tgz files in numbered subfolders under this path, based on dependency tree layers (leaves first). There will also be a file `versions.json` at the top level with the versions of the packed packages in each layer.
`publish`	`boolean`	`true`	repo	Whether to publish to npm registry
`push`	`boolean`	`true`	repo	Whether to push to the remote git branch
`registry`	`string`	as configured for npm	npm registry to use (required if you've explicitly configured authentication for beachball)
`retries`	`number`	`3`	repo	Number of retries for a package publish before failing
`scope`	`string[]`		repo	Only consider package paths matching these patterns (see details)
`shouldPublish`	`false \| undefined`		package	In most cases you should use `private: true` in `package.json` instead. This option skips the `npm publish` (or `pack`) step for this package, but it's still bumped, tagged, and gets changelog entries. Does not work to force publishing.
`tag`	`string`	see notes	repo, package	`dist-tag` for npm when published. Defaults to `defaultNpmTag` or `'latest'` (npm does NOT allow publishing packages without a `dist-tag`).
`transform`	`TransformOptions`		repo	Transformations for change files

Glob matching

Glob matching is implemented using Node's built-in glob support, which is based on minimatch with these options and supports most glob syntax.

Patterns are relative to the repo or project root.
Patterns should use forward slashes.
Case-sensitive matching behavior varies by OS, so it's best to ensure the patterns follow the actual casing used by files.
Unless otherwise noted (such as for scope), using gitignore-style negated patterns to modify previous matches is not supported.

Scoping

The scope option allows limiting which packages are considered. You can set it in the config file if it should always apply, or on the command line for a specific operation.

This option takes a list of patterns which are matched against package paths. Patterns are relative to the monorepo root and should use forward slashes. Negations are supported, similar to how gitignore works.

Example: with this config, beachball will only consider packages under packages/foo (excluding packages/foo/bar).

// in beachball.config.js or root package.json "beachball"
{
  "scope": ["packages/foo/*", "!packages/foo/bar"]
}

On the command line, this could be specified as --scope 'packages/foo/*' --scope '!packages/foo/bar' (don't forget the quotes!).

Note: if you have multiple sets of packages in the repo with different scopes, groupChanges is not supported.

Specifying the target branch and remote

The branch option is the official target branch to compare against when determining changes.

Repos which may have forks

If you have a public GitHub repo or another situation where any contributions might come from a fork, branch should use the name only (no remote) (since users can choose arbitrary names for their own remote and the official remote):

// in beachball.config.js or root package.json "beachball"
{
  "branch": "main"
}

To ensure Beachball can reliably determine which local remote name corresponds to the official remote, set repository in the repo root package.json:

// repo root package.json
{
  "repository": {
    "type": "git",
    // your repository URL here (most formats are supported)
    "url": "https://github.com/microsoft/beachball"
  }
}

Repos with a single remote (mostly Azure DevOps)

If all your contributors use branches on a single remote (as opposed to forking), you can specify the remote name as part of the branch setting. This is almost always the model used in internal Azure DevOps repos. (Do NOT use this approach for public GitHub repos.)

// in beachball.config.js or root package.json "beachball"
{
  "branch": "origin/main"
}

For safety as a fallback, it's still recommended to set repository in your repo root package.json as detailed above.

How Beachball determines the branch and remote

If branch isn't specified, the default branch name is the system default branch name (main or master).

If branch doesn't include a remote (or isn't specified), Beachball will first look for a remote matching package.json repository. If that's not found, the fallback remote is upstream if defined, origin if defined, or the first defined remote.

All the fallback logic involves git operations, so especially in large repos, it's best to give Beachball a hint using one of the approaches specified above for efficiency.