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

beachball uses cosmiconfig to read its configuration, so you can specify configuration in several ways (in addition to CLI arguments).

"beachball" key inside package.json
.beachballrc
.beachballrc.json
beachball.config.js (CJS or ESM depending on your project setup; explicit .cjs or .mjs is also supported)

It's most common to use a JavaScript file for the repo-level config, since it's the most flexible and allows comments. Usually this file is at the repo root.

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 RepoOptions in this file.

"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'`	`'restricted'`	repo	publish access level for scoped package names (e.g. `@foo/bar`)
`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)
`changeFilePrompt`	`ChangeFilePromptOptions`		repo	customize the prompt for change files (can be used to add custom fields)
`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
`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'`	`true`	repo	whether to generate `CHANGELOG.md/json` (`'md'` or `'json'` to generate only that type)
`gitTags`	`boolean`	`true`	repo, package	whether to create git tags for published packages (eg: foo_v1.0.1)
`groups`	`VersionGroupOptions[]`		repo	bump these packages together (see details)
`groupChanges`	`boolean`	`false`	repo	write multiple changes to a single changefile
`hooks`	`HooksOptions`		repo	hooks for custom pre/post publish actions
`ignorePatterns`	`string[]`		repo	ignore changes in files matching these glob patterns (see notes)
`package`	`string`		repo	specifies which package the command relates to (overrides change detection based on `git diff`)
`prereleasePrefix`	`string`		repo	prerelease prefix for packages that are specified to receive a prerelease bump
`publish`	`boolean`	`true`	repo	whether to publish to npm registry
`push`	`boolean`	`true`	repo	whether to push to the remote git branch
`registry`	`string`		repo	target NPM registry to publish
`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	manually disable publishing of a package by beachball (does not work to force publishing)
`tag`	`string`	`'latest'`	repo, package	dist-tag for npm when published
`transform`	`TransformOptions`		repo	transformations for change files

Glob matching

Glob matching is implemented using minimatch, which supports most glob syntax.

All glob patterns are relative to the repo or monorepo root and must use forward slashes only.

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 must 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).

{
  "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.

Determining the target branch and remote

The branch option is the official target branch to compare against when determining changes. Usually it should be a name only, though you can also include a remote. The default is the system default branch name (main or master) and the official remote.

To let beachball reliably determine the official remote, it's recommended to specify repository in the repo root package.json. This allows matching via URL regardless of what the user decided to call the remote.

If repository isn't specified and branch doesn't include a remote, the fallback is upstream if defined, origin if defined, or the first defined remote.