@lerna-lite/publish
Advanced tools
lerna publish) - Publish command ☁️Lerna-Lite Publish command, publish package(s) in the current project
# simple install or install it globally with -g
npm install @lerna-lite/cli -D -W
# then use it (see usage below)
lerna publish
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:
lerna version behind the scenes).
describeTag pattern (For details, refer to lerna version).from-git).from-package).lerna will never publish packages which are marked as private (
"private": truein thepackage.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.
Note: See the FAQ for information on how to recover from a failed publish.
--bump from-gitIn 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-packageSimilar 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.
lerna publish supports all of the options provided by lerna version in addition to the following:
@lerna/publish
--canary--cleanup-temp-files (new)--contents <dir>--dist-tag <tag>--force-publish--git-head <sha>--graph-type <all|dependencies>--ignore-scripts--ignore-prepublish--legacy-auth--no-git-reset--no-granular-pathspec--otp--preid--pre-dist-tag <tag>--remove-package-fields <fields> (new)--registry <url>--tag-version-prefix--temp-tag--summary-file <dir> (new)--verify-access--yespublishConfig Overridesworkspace: protocol
--canarylerna 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.
Canary releases cannot be used in conjunction with the --build-metadata option.
--cleanup-temp-filesCleanup the temp folders used by the publish process once the execution is over, defaults to false.
lerna publish --cleanup-temp-files
Note Lerna-Lite is prefixing the temp folders containing each package tarball with "lerna-", we then use a glob pattern to delete every folders starting with this prefix. Also note that it is entirely possible that this cleanup misses some extra temp files created by the publish process.
--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
latesttag is the one that is used when a user runsnpm install my-package. To install a different tag, a user can runnpm install my-package@prerelease.
--force-publishTo 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-scriptsWhen passed, this flag will disable running lifecycle scripts during lerna publish.
--ignore-prepublishWhen passed, this flag will disable running deprecated prepublish scripts during lerna publish.
--legacy-authWhen 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-resetBy 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-pathspecBy 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.
--otpWhen 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.
--preidUnlike 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.
--remove-package-fields <fields>Remove certain fields from every package before publishing them to the registry, we can also remove fields from a complex object structure via the dot notation (ie "scripts.build"). In summary this option is helpful in cleaning each "package.json" of every packages, it allows us to remove any extra fields that do not have any usage outside of the project itself (for example "devDependencies", "scripts", ...).
# remove "devDepencies" and "scripts" fields from all packages
lerna version --remove-package-fields 'devDependencies' 'scripts'
Removal of complex object value(s) are also supported via the dot notation as shown below.
lerna version --remove-package-fields 'scripts.build'
{
script: {
- "build": "tsc --project tsconfig.json",
"build:dev": "tsc --incremental --watch"
}
}
This option is probably best specified in lerna.json configuration
{
"command": {
"publish": {
"removePackageFields": ["devDependencies", "scripts"]
}
}
}
--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-prefixThis 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-tagWhen 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.
--summary-file# Will create a summary file in the root directory, i.e. `./lerna-publish-summary.json`
lerna publish --canary --yes --summary-file
# Will create a summary file in the provided directory, i.e. `./some/other/dir/lerna-publish-summary.json`
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"
}
]
--verify-accessHistorically, 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:
npm access ls-packages--yeslerna 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.
A leaf package can be configured with special publishConfig that in certain circumstances changes the behavior of lerna publish.
publishConfig.accessTo 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.registryYou can customize the registry on a per-package basis by setting registry:
"publishConfig": {
"registry": "http://my-awesome-registry.com/"
}
--registry applies globally, and in some cases isn't what you want.publishConfig.tagYou can customize the dist-tag on a per-package basis by setting tag:
"publishConfig": {
"tag": "flippin-sweet"
}
--dist-tag will overwrite this value.--canary is passed.publishConfig.directoryThis 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"
}
publishConfig OverridesCertain fields defined in publishConfig can be used to override other fields in the manifest before the package gets published. As per pnpm publishConfig documentation, you can override any of these fields:
bin, browser, cpu, esnext, es2015, exports, imports, libc, main, module, os, type, types, typings, typesVersions, umd:main, unpkgNote this option is enabled by default but can be disabled bia
lerna publish --no-publish-config-overridesor ("publishConfigOverrides": falseinlerna.json)
For instance, the following package.json:
{
"name": "foo",
"version": "1.0.0",
"main": "src/index.ts",
"publishConfig": {
"main": "lib/index.js",
"typings": "lib/index.d.ts"
}
}
Will be published as:
{
"name": "foo",
"version": "1.0.0",
"main": "lib/index.js",
"typings": "lib/index.d.ts"
}
// 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:
prepublish lifecycle in root, if enabledprepare lifecycle in rootprepublishOnly lifecycle in rootprepack lifecycle in rootpostpack lifecycle in rootpublish lifecycle in root
lerna publishpostpublish lifecycle in rootworkspace: protocolThe workspace: protocol (pnpm workspace, yarn workspace) is also supported by Lerna-Lite. We also strongly suggest that you use this in combo with the new --sync-workspace-lock flag to properly update your root project lock file. When publishing, it will replace any workspace: dependencies by:
workspace:*, workspace:~, or workspace:^)So for example, if we have foo, bar, qar, zoo in the workspace and they all are at version 1.5.0 (before publishing), the following:
{
"dependencies": {
"foo": "workspace:*",
"bar": "workspace:~",
"qar": "workspace:^",
"zoo": "workspace:^1.5.0"
}
}
Note semver range with an operator (ie
workspace:>=2.0.0) are also supported but will never be mutated.
--workspace-strict-match (default)When using strict match (default), it will be transformed and publish with the following:
this is the default and is usually what most user will want to use since it will strictly adhere to pnpm/yarn workspace protocol.
{
"dependencies": {
"foo": "1.5.0",
"bar": "~1.5.0",
"qar": "^1.5.0",
"zoo": "^1.5.0"
}
}
--no-workspace-strict-match (deprecated)When strict match is disabled, it will be transformed and publish with the following:
you would rarely want to disable the strict match, in fact this option will be removed entirely in a future release, this flag was created for the sole purpose of making it compatible with previous Lerna-Lite version 1.2.0. When disabled, in most cases Lerna will assume that the caret (^) is needed unless the option --exact is provided and by doing so will not be strictly following pnpm/yarn workspace protocol and for that reason is not recommended.
{
"dependencies": {
"foo": "^1.5.0",
"bar": "^1.5.0",
"qar": "^1.5.0",
"zoo": "^1.5.0"
}
}
In the case that some packages were successfully published and others were not, lerna publish may have left the repository in an inconsistent state with some changed files. To recover from this, reset any extraneous local changes from the failed run to get back to a clean working tree. Then, retry the same lerna publish command. Lerna will attempt to publish all of the packages again, but will recognize those that have already been published and skip over them with a warning.
If you used the lerna publish command without positional arguments to select a new version for the packages, then you can run lerna publish from-git to retry publishing that same already-tagged version instead of having to bump the version again while retrying.
--no-verify-accessThe 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-npmCall lerna version directly, instead.
--no-workspace-strict-matchProviding --no-workspace-strict-match is deprecated and will be removed in future version, we will make workspace: protocol strict matching in every case.
FAQs
Publish packages in the current workspace
The npm package @lerna-lite/publish receives a total of 16,930 weekly downloads. As such, @lerna-lite/publish popularity was classified as popular.
We found that @lerna-lite/publish demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh joins Insecure Agents to discuss CVE remediation and why supply chain attacks require a different security approach.
Security News
Tailwind Labs laid off 75% of its engineering team after revenue dropped 80%, as LLMs redirect traffic away from documentation where developers discover paid products.
Security News
The planned feature introduces a review step before releases go live, following the Shai-Hulud attacks and a rocky migration off classic tokens that disrupted maintainer workflows.