@lerna/publish

@lerna/publish

Publish packages in the current project

Install lerna for access to the lerna CLI.

Usage

lerna publish              # publish packages that have changed since the last release
lerna publish from-git     # explicitly publish packages tagged in the current commit
lerna publish from-package # explicitly publish packages where the latest version is not present in the registry

When run, this command does one of the following things:

• Publish packages updated since the last release (calling lerna version behind the scenes).
  • This is the legacy behavior of lerna 2.x
• Publish packages tagged in the current commit (from-git).
• Publish packages in the latest commit where the version is not present in the registry (from-package).
• Publish an unversioned "canary" release of packages (and their dependents) updated in the previous commit.

Lerna will never publish packages which are marked as private ("private": true in the package.json).

During all publish operations, appropriate lifecycle scripts are called in the root and per-package (unless disabled by `--ignore-scripts).

Check out Per-Package Configuration for more details about publishing scoped packages, custom registries, and custom dist-tags.

Positionals

bump from-git

In addition to the semver keywords supported by lerna version, lerna publish also supports the from-git keyword. This will identify packages tagged by lerna version and publish them to npm. This is useful in CI scenarios where you wish to manually increment versions, but have the package contents themselves consistently published by an automated process.

bump from-package

Similar to the from-git keyword except the list of packages to publish is determined by inspecting each package.json and determining if any package version is not present in the registry. Any versions not present in the registry will be published. This is useful when a previous lerna publish failed to publish all packages to the registry.

Options

lerna publish supports all of the options provided by lerna version in addition to the following:

• --canary
• --contents <dir>
• --dist-tag <tag>
• --git-head <sha>
• --graph-type <all|dependencies>
• --ignore-scripts
• --ignore-prepublish
• --legacy-auth
• --no-git-reset
• --no-granular-pathspec
• --verify-access
• --otp
• --preid
• --pre-dist-tag <tag>
• --registry <url>
• --tag-version-prefix
• --temp-tag
• --yes

--canary

lerna publish --canary
# 1.0.0 => 1.0.1-alpha.0+${SHA} of packages changed since the previous commit
# a subsequent canary publish will yield 1.0.1-alpha.1+${SHA}, etc

lerna publish --canary --preid beta
# 1.0.0 => 1.0.1-beta.0+${SHA}

# The following are equivalent:
lerna publish --canary minor
lerna publish --canary preminor
# 1.0.0 => 1.1.0-alpha.0+${SHA}

When run with this flag, lerna publish publishes packages in a more granular way (per commit). Before publishing to npm, it creates the new version tag by taking the current version, bumping it to the next minor version, adding the provided meta suffix (defaults to alpha) and appending the current git sha (ex: 1.0.0 becomes 1.1.0-alpha.0+81e3b443).

If you have publish canary releases from multiple active development branches in CI, it is recommended to customize the --preid and --dist-tag <tag> on a per-branch basis to avoid clashing versions.

The intended use case for this flag is a per commit level release or nightly release.

--contents <dir>

Subdirectory to publish. Must apply to ALL packages, and MUST contain a package.json file. Package lifecycles will still be run in the original leaf directory. You should probably use one of those lifecycles (prepare, prepublishOnly, or prepack) to create the subdirectory and whatnot.

If you're into unnecessarily complicated publishing, this will give you joy.

lerna publish --contents dist
# publish the "dist" subfolder of every Lerna-managed leaf package

NOTE: You should wait until the postpublish lifecycle phase (root or leaf) to clean up this generated subdirectory, as the generated package.json is used during package upload (after postpack).

--dist-tag <tag>

lerna publish --dist-tag next

When run with this flag, lerna publish will publish to npm with the given npm dist-tag (defaults to latest).

This option can be used to publish a prerelease or beta version under a non-latest dist-tag, helping consumers avoid automatically upgrading to prerelease-quality code.

Note: the latest tag is the one that is used when a user runs npm install my-package. To install a different tag, a user can run npm install my-package@prerelease.

--git-head <sha>

Explicit SHA to set as gitHead on manifests when packing tarballs, only allowed with from-package positional.

For example, when publishing from AWS CodeBuild (where git is not available), you could use this option to pass the appropriate environment variable to use for this package metadata:

lerna publish from-package --git-head ${CODEBUILD_RESOLVED_SOURCE_VERSION}

Under all other circumstances, this value is derived from a local git command.

--graph-type <all|dependencies>

Set which kind of dependencies to use when building a package graph. The default value is dependencies, whereby only packages listed in the dependencies section of a package's package.json are included. Pass all to include both dependencies and devDependencies when constructing the package graph and determining topological order.

When using traditional peer + dev dependency pairs, this option should be configured to all so the peers are always published before their dependents.

lerna publish --graph-type all

Configured via lerna.json:

{
  "command": {
    "publish": {
      "graphType": "all"
    }
  }
}

--ignore-scripts

When passed, this flag will disable running lifecycle scripts during lerna publish.

--ignore-prepublish

When passed, this flag will disable running deprecated prepublish scripts during lerna publish.

--legacy-auth

When publishing packages that require authentication but you are working with an internally hosted NPM Registry that only uses the legacy Base64 version of username:password. This is the same as the NPM publish _auth flag.

lerna publish --legacy-auth aGk6bW9t

--no-git-reset

By default, lerna publish ensures any changes to the working tree have been reset.

To avoid this, pass --no-git-reset. This can be especially useful when used as part of a CI pipeline in conjunction with the --canary flag. For instance, the package.json version numbers which have been bumped may need to be used in subsequent CI pipeline steps (such as Docker builds).

lerna publish --no-git-reset

--no-granular-pathspec

By default, lerna publish will attempt (if enabled) to git checkout only the leaf package manifests that are temporarily modified during the publishing process. This yields the equivalent of git checkout -- packages/*/package.json, but tailored to exactly what changed.

If you know you need different behavior, you'll understand: Pass --no-granular-pathspec to make the git command literally git checkout -- .. By opting into this pathspec, you must have all intentionally unversioned content properly ignored.

This option makes the most sense configured in lerna.json, as you really don't want to mess it up:

{
  "version": "independent",
  "granularPathspec": false
}

The root-level configuration is intentional, as this also covers the identically-named option in lerna version.

--verify-access

Historically, lerna attempted to fast-fail on authorization/authentication issues by performing some preemptive npm API requests using the given token. These days, however, there are multiple types of tokens that npm supports and they have varying levels of access rights, so there is no one-size fits all solution for this preemptive check and it is more appropriate to allow requests to npm to simply fail with appropriate errors for the given token. For this reason, the legacy --verify-access behavior is disabled by default and will likely be removed in a future major version.

For now, though, if you pass this flag you can opt into the legacy behavior and lerna will preemptively perform this verification before it attempts to publish any packages.

You should NOT use this option if:

1. You are using a third-party registry that does not support npm access ls-packages
2. You are using an authentication token without read access, such as a npm automation access token

--otp

When publishing packages that require two-factor authentication, you can specify a one-time password using --otp:

lerna publish --otp 123456

Please keep in mind that one-time passwords expire within 30 seconds of their generation. If it expires during publish operations, a prompt will request a refreshed value before continuing.

--preid

Unlike the lerna version option of the same name, this option only applies to --canary version calculation.

lerna publish --canary
# uses the next semantic prerelease version, e.g.
# 1.0.0 => 1.0.1-alpha.0

lerna publish --canary --preid next
# uses the next semantic prerelease version with a specific prerelease identifier, e.g.
# 1.0.0 => 1.0.1-next.0

When run with this flag, lerna publish --canary will increment premajor, preminor, prepatch, or prerelease semver bumps using the specified prerelease identifier.

--pre-dist-tag <tag>

lerna publish --pre-dist-tag next

Works the same as --dist-tag, except only applies to packages being released with a prerelease version.

--registry <url>

When run with this flag, forwarded npm commands will use the specified registry for your package(s).

This is useful if you do not want to explicitly set up your registry configuration in all of your package.json files individually when e.g. using private registries.

--tag-version-prefix

This option allows to provide custom prefix instead of the default one: v.

Keep in mind, if splitting lerna version and lerna publish, you need to pass it to both commands:

# locally
lerna version --tag-version-prefix=''

# on ci
lerna publish from-git --tag-version-prefix=''

You could also configure this at the root level of lerna.json, applying to both commands equally:

{
  "tagVersionPrefix": "",
  "packages": ["packages/*"],
  "version": "independent"
}

--temp-tag

When passed, this flag will alter the default publish process by first publishing all changed packages to a temporary dist-tag (lerna-temp) and then moving the new version(s) to the dist-tag configured by --dist-tag (default latest).

This is not generally necessary, as Lerna will publish packages in topological order (all dependencies before dependents) by default.

--yes

lerna publish --canary --yes
# skips `Are you sure you want to publish the above changes?`

When run with this flag, lerna publish will skip all confirmation prompts. Useful in Continuous integration (CI) to automatically answer the publish confirmation prompt.

Deprecated Options

--no-verify-access

The legacy preemptive access verification is now off by default, so --no-verify-access is not needed. Requests will fail with appropriate errors when not authorized correctly. To opt-in to the legacy access verification, use --verify-access.

--skip-npm

Call lerna version directly, instead.

Per-Package Configuration

A leaf package can be configured with special publishConfig that in certain circumstances changes the behavior of lerna publish.

publishConfig.access

To publish packages with a scope (e.g., @mycompany/rocks), you must set access:

  "publishConfig": {
    "access": "public"
  }

• If this field is set for a package without a scope, it will fail.

• If you want your scoped package to remain private (i.e., "restricted"), there is no need to set this value.

  Note that this is not the same as setting "private": true in a leaf package; if the private field is set, that package will never be published under any circumstances.

publishConfig.registry

You can customize the registry on a per-package basis by setting registry:

  "publishConfig": {
    "registry": "http://my-awesome-registry.com/"
  }

• Passing --registry applies globally, and in some cases isn't what you want.

publishConfig.tag

You can customize the dist-tag on a per-package basis by setting tag:

  "publishConfig": {
    "tag": "flippin-sweet"
  }

• Passing --dist-tag will overwrite this value.
• This value is always ignored when --canary is passed.

publishConfig.directory

This non-standard field allows you to customize the published subdirectory just like --contents, but on a per-package basis. All other caveats of --contents still apply.

  "publishConfig": {
    "directory": "dist"
  }

Lifecycle Scripts

// prepublish:      Run BEFORE the package is packed and published.
// prepare:         Run BEFORE the package is packed and published, AFTER prepublish, BEFORE prepublishOnly.
// prepublishOnly:  Run BEFORE the package is packed and published, ONLY on npm publish.
// prepack:     Run BEFORE a tarball is packed.
// postpack:    Run AFTER the tarball has been generated and moved to its final destination.
// publish:     Run AFTER the package is published.
// postpublish: Run AFTER the package is published.

Lerna will run npm lifecycle scripts during lerna publish in the following order:

1. If versioning implicitly, run all version lifecycle scripts
2. Run prepublish lifecycle in root, if enabled
3. Run prepare lifecycle in root
4. Run prepublishOnly lifecycle in root
5. Run prepack lifecycle in root
6. For each changed package, in topological order (all dependencies before dependents):
   1. Run prepublish lifecycle, if enabled
   2. Run prepare lifecycle
   3. Run prepublishOnly lifecycle
   4. Run prepack lifecycle
   5. Create package tarball in temp directory via JS API
   6. Run postpack lifecycle
7. Run postpack lifecycle in root
8. For each changed package, in topological order (all dependencies before dependents):
   1. Publish package to configured registry via JS API
   2. Run publish lifecycle
   3. Run postpublish lifecycle
9. Run publish lifecycle in root
   • To avoid recursive calls, don't use this root lifecycle to run lerna publish
10. Run postpublish lifecycle in root
11. Update temporary dist-tag to latest, if enabled

Changelog

6.0.0 (2022-10-12)

Super fast, modern task-runner implementation for lerna run

As of version 6.0.0, Lerna will now delegate the implementation details of the lerna run command to the super fast, modern task-runner (powered by Nx) by default.

If for some reason you wish to opt in to the legacy task-runner implementation details (powered by p-map and p-queue), you can do so by setting "useNx": false in your lerna.json. (Please let us know via a Github issue if you feel the need to do that, however, as in general the new task-runner should just work how you expect it to as a lerna user).

Interactive configuration for lerna run caching and task pipelines via the new lerna add-caching command

When using the modern task-runner implementation described above, the way to get the most out of it is to tell it about the outputs of your various scripts, and also any relationships that exist between them (such as needing to run the build script before the test, for example).

Simply run lerna add-caching and follow the instructions in order to generate all the relevant configuration for your workspace.

You can learn more about the configuration it generates here: https://lerna.js.org/docs/concepts/task-pipeline-configuration

Automatic loading of .env files in lerna run with the new task-runner implementation

By default the modern task runner powered by Nx will automatically load .env files for you. You can set --load-env-files to false if you want to disable this behavior for any reason.

For more details about what .env files will be loaded by default please see: https://nx.dev/recipes/environment-variables/define-environment-variables

Obsolete options in lerna run with the new task-runner implementation

There are certain legacy options for lerna run which are no longer applicable to the modern task-runner. Please see full details about those flags, and the reason behind their obselence, here:

https://lerna.js.org/docs/lerna6-obsolete-options

New lerna repair command

When configuration changes over time as new versions of a tool are published it can be tricky to keep up with the changes and sometimes it's possible to miss out on optimizations as a result.

When you run the new command lerna repair, lerna will execute a series of code migrations/codemods which update your workspace to the latest and greatest best practices for workspace configuration.

The actual codemods which run will be added to over time, but for now one you might see run on your workspace is that it will remove any explicit "useNx": true references from lerna.json files, because that is no longer necessary and it's cleaner not to have it.

We are really excited about this feature and how we can use it to help users keep their workspaces up to date.