publish.md

tags	cli
category	doc

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
--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_TOKEN environment variable (beachball passes this through to npm)
• Run npm login first (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:

1. Validate that options and change files are valid
2. Bump and publish to npm (unless disabled):
   1. Bump the package versions locally
   2. Generate the changelog files (unless disabled)
   3. Delete change files locally (unless disabled)
   4. Validate that nothing to be published depends on a private package
   5. 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)
3. Bump and push to git (unless bumping or pushing is disabled):
   1. Revert any previous changes (from the publish step)
   2. Merge the latest changes from the remote branch to avoid merge conflicts (unless fetching is disabled)
   3. Bump the versions locally
   4. Generate the changelog files (unless disabled)
   5. Delete change files locally (unless disabled)
   6. Commit the changes
   7. Create git tags for new package versions (unless disabled)
   8. 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.