publish
Bumps package versions, publishes to the npm registry, and pushes file updates and tags to the git remote.
Options
General options also apply for this command.
Most options can also be specified in the configuration file, which is generally preferable as it's easier to read and maintain.
| Option | Alias | Default | Description |
|---|---|---|---|
--access | 'restricted' | Publish access level: 'restricted' or 'public'. This should almost always be set to 'public'. | |
--auth-type | -a | 'authtoken' | npm auth type for NPM_TOKEN or --token: 'authtoken' or 'password' |
--git-tags, --no-git-tags | true (--git-tags) | whether to create git tags for published package versions | |
--keep-change-files | don't delete the change files from disk after bumping | ||
--message | -m | 'applying package updates' | custom commit message |
--prerelease-prefix | prerelease prefix (e.g. beta) for packages that will receive a prerelease bump | ||
--publish, --no-publish | true (--publish) | whether to publish to the npm registry | |
--push, --no-push | true (--push) | whether to commit changes and push them back to the git remote | |
--registry | -r | 'https://registry.npmjs.org' | npm registry for publishing |
--retries | 3 | number of retries for a package publish before failing | |
--tag | -t | 'latest' | dist-tag for npm publishes |
--token | -n | Not recommended; see alternatives | |
--verbose | false | prints additional information to the console | |
--yes | -y | if CI detected, true | skips the prompts for publish |
CI integration
See the CI integration page for details about how to handle git and npm authentication while publishing, as well as complete example workflows.
Note that if running beachball publish manually on your local machine, there's the additional option of authenticating with npm via npm login.
Publish algorithm
The publish command is designed to run steps in an order that minimizes the chances of mid-publish failure by doing validation upfront.
beachball publish performs the following steps:
- Validate that options and change files are valid
- Bump and publish to npm (unless disabled):
- Bump the package versions locally
- Generate the changelog files (unless disabled)
- Delete change files locally (unless disabled)
- Validate that the package versions to be published don't already exist in the registry and don't depend on any private packages
- Publish packages to npm in topological order based on the dependency graph (so if there's a failure partway through, a published package won't reference unpublished versions)
- Bump and push to git (unless bumping or pushing is disabled):
- Revert any previous changes (from the publish step)
- Merge the latest changes from the remote branch to avoid merge conflicts (unless fetching is disabled)
- Bump the versions locally
- Generate the changelog files (unless disabled)
- Delete change files locally (unless disabled)
- Commit the changes
- Create git tags for new package versions (unless disabled)
- Push the changes and tags
It might be surprising that beachball publish does so many steps, especially the step about reverting changes! In most version bumping systems that automate syncing the git repo and npm registry, they assume that the source code is still fresh once it's time to push changes back to the git repository. This is rarely the case for large repos with many developers. So, beachball fetches the latest changes before pushing back to the target branch to avoid merge conflicts.
Recovering from failed publish
If the publish command fails partway through, after some versions have been published to the registry, you'll need to run beachball sync and commit the changes.