beachball

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

  1. repository config
  2. package config

# Configuration files

beachball uses cosmiconfig (opens new window) 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

# beachball.config.js

In many cases, you'll want to use a JavaScript config file (written as a CommonJS module), since this is the most flexible and allows comments.

module.exports = {
  key: value,
  key2: value2
  key3: value3
}

Config files can be placed in either the root of a repo and/or within individual packages (package config overrides the repo config where applicable). For example:

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

It's also common to have a repo-level beachball.config.js and any individual package overrides (if they're simple) in the "beachball" key in the package's package.json.

# Options

For the latest full list of supported options, see RepoOptions in this file (opens new window).

Option Type Default Option Type Description
access 'public' or 'restricted' 'restricted' repo publishes private packages access level
branch string 'origin/master' repo the target branch (with remote)
bumpDeps bool true repo bump dependent packages during publish (bump A if A depends on B)
changeFilePrompt ChangeFilePromptOptions (details (opens new window)) 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 of the change files
changelog ChangelogOptions (details (opens new window)) repo changelog rendering and grouping options
defaultNpmTag string 'latest' package the default dist-tag used for NPM publish
disallowedChangeTypes string[] repo, group, package what change types are disallowed
fetch bool true repo fetch from remote before doing diff comparisons
generateChangelog bool, 'md', or 'json' true repo whether to generate CHANGELOG.md/json ('md' or 'json' to generate only that type)
gitTags bool true repo, package whether to create git tags for published packages (eg: foo_v1.0.1)
groups VersionGroupOptions[] (details) repo specifies groups of packages that need to be version bumped at the same time
groupChanges bool false repo will write multiple changes to a single changefile
hooks HooksOptions (details (opens new window)) repo hooks for custom pre/post publish actions
ignorePatterns string[] repo ignore changes in these files (minimatch patterns; negations not supported)
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 bool true repo whether to publish to npm registry
push bool 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
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 (details (opens new window)) repo transformations for change files

← Bump Algorithm →