lerna publish
Publish packages in the current project
Install lerna for access to the lerna
CLI.
Usage
lerna publish
lerna publish from-git
lerna publish from-package
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 not publish packages which are marked as private ("private": true
in the package.json
). This is consistent with the behavior of npm publish
. See the package.json docs for more information. To override this behavior, see the --include-private
option.
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.
Note: See the FAQ for information on how to recover from a failed publish.
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
lerna publish --canary
lerna publish --canary --preid beta
lerna publish --canary minor
lerna publish --canary preminor
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.
NOTE: Canary releases cannot be used in conjunction with the --build-metadata
option.
--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
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
.
--force-publish
To be used with --canary
to publish a canary version of all packages in your monorepo. This flag can be helpful when you need to make canary releases of packages beyond what was changed in the most recent commit.
lerna publish --canary --force-publish
--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
.
--include-private
Indicates a list of packages marked with "private": true
that should be published. Since npm publish
refuses to publish any packages with "private": true
, Lerna removes the property before publishing.
Note that this is different than private scoped packages, which do not have "private": true
in their package.json
, are intended to be published, and are included by lerna publish
by default. See the npm docs for more information about these kind of packages.
⚠️ CAUTION ⚠️: Packages marked with "private": true
are not intended to be published, as detailed in the npm package.json docs. The intended use of this option is to allow publishing packages that will be public in the future to a local registry for testing purposes.
Examples:
lerna publish --include-private my-private-package
lerna publish --include-private my-private-package my-other-private-package
The wildcard "*" may also be provided in place of a list of packages. In this case, all private packages will be published.
lerna publish --include-private "*"
Quotes must be placed around "*" to prevent the shell from prematurely expanding it.
--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:
- You are using a third-party registry that does not support
npm access ls-packages
- 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
lerna publish --canary --preid next
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:
lerna version --tag-version-prefix=''
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
When run with this flag, lerna publish
will skip all confirmation prompts.
Useful in Continuous integration (CI) to automatically answer the publish confirmation prompt.
--summary-file
lerna publish --canary --yes --summary-file
lerna publish --canary --yes --summary-file ./some/other/dir
When run with this flag, a json summary report will be generated after all packages have been successfully published (see below for an example).
[
{
"packageName": "package1",
"version": "v1.0.1-alpha"
},
{
"packageName": "package2",
"version": "v2.0.1-alpha"
}
]
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 not be published. For more information, see the --include-private
option.
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
Lerna will run npm lifecycle scripts during lerna publish
in the following order:
- If versioning implicitly, run all version lifecycle scripts
- Run
prepublish
lifecycle in root, if enabled - Run
prepare
lifecycle in root - Run
prepublishOnly
lifecycle in root - Run
prepack
lifecycle in root - For each changed package, in topological order (all dependencies before dependents):
- Run
prepublish
lifecycle, if enabled - Run
prepare
lifecycle - Run
prepublishOnly
lifecycle - Run
prepack
lifecycle - Create package tarball in temp directory via JS API
- Run
postpack
lifecycle
- Run
postpack
lifecycle in root - For each changed package, in topological order (all dependencies before dependents):
- Publish package to configured registry via JS API
- Run
publish
lifecycle - Run
postpublish
lifecycle
- Run
publish
lifecycle in root
- To avoid recursive calls, don't use this root lifecycle to run
lerna publish
- Run
postpublish
lifecycle in root - Update temporary dist-tag to latest, if enabled