publish
Publishing automates all the bumping and synchronizing of package versions in the git remote as well as the npm registry.
Options
General options also apply for this command.
| Option | Alias | Default | Description |
|---|---|---|---|
--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 below | |
--verbose | false | prints additional information to the console | |
--yes | -y | if CI detected, true | skips the prompts for publish |
Providing a token
There are a few different ways to handle npm authentication for beachball publish.
In CI, you should use trusted publishing if supported to remove the need for tokens. Unfortunately this isn't available in Azure DevOps.
If trusted publishing is unavailable or you're running beachball locally, you can do any of the following:
- Set the
NPM_TOKENenvironment variable (beachballpasses this through tonpm) - Run
npm loginfirst (or a task which does the same) - Manually set the token in
.npmrc, possibly referencing an environment variable - Old way: use
--token <token>on the command line (not recommended)
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 nothing to be published depends on a private package
- Publish packages to npm in topological order based on the dependency graph (to reduce the chances that if there's a failure partway through, a published package might require 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.
Example CI workflow
See the CI integration page details and examples for how to run beachball publish in CI.
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.