$3

Only configurable via lerna.json since an object type must be provided:

`json
{
"command": {
"publish": {
"arboristLoadOptions": { "ignoreMissing": true }
}
}
}
`

$3

`sh
lerna publish --canary


1.0.0 => 1.0.1-alpha.0.${SHA} of packages changed since the previous commit

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 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.

$3

Cleanup the temp folders used by the publish process once the execution is over, defaults to false.

`sh
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.

$3

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.

`sh
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).

$3

`sh
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.

$3

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.

`sh
lerna publish --canary --force-publish
`

$3

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:

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

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

$3

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.

`sh
lerna publish --graph-type all
`

Configured via lerna.json:

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

$3

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

$3

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

$3

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.

`sh
lerna publish --legacy-auth aGk6bW9t
`

$3

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).

`sh
lerna publish --no-git-reset
`

$3

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:

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

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

$3

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

`sh
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.

$3

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

`sh
lerna publish --canary


uses the next semantic prerelease version, e.g.

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

$3

`sh
lerna publish --pre-dist-tag next
`

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

$3

`sh


strip "devDepencies" and "scripts" fields from all packages

> Note lifecycle scripts (prepublish, prepublishOnly, prepack, postpack) are executed after the field removal process and for that reason, if any of these scripts are found, it will leave them in place and skip the removal whenever found.

> Note this option will actually temporarily modify the actual package.json just before the publish process starts and will then revert the changes after the publish process is completed. If for whatever reason, your publish process fails, it is possible that your packages are transformed into an invalid state (e.g. scripts could be stripped), so it very important to review your package.json after a publish failure.

Removal of complex object value(s) are also supported via the dot notation as shown below.

`sh
lerna version --strip-package-keys 'scripts.build'
`

##### output

`diff
{
script: {
- "build": "tsc --project tsconfig.json",
"build:dev": "tsc --incremental --watch"
}
}
`

This option might be better defined via lerna.json configuration

`json
{
"command": {
"publish": {
"stripPackageKeys": ["devDependencies", "scripts"]
}
}
}
`

$3

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.

$3

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:

`bash


locally

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

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

$3

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.

$3

`sh


Will create a summary file in the root directory, i.e. ./lerna-publish-summary.json

Will create a summary file in the provided directory, i.e. ./some/other/dir/lerna-publish-summary.json

Will create a summary file with the provided name, i.e. ./some/other/dir/my-summary.json

`json
[
{
"packageName": "package1",
"version": "v1.0.1-alpha"
},
{
"packageName": "package2",
"version": "v2.0.1-alpha"
}
]
`

$3

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

$3

This option class allows to throttle the timing at which modules are published to the configured registry.

- --throttle: Enable throttling when publishing modules
- --throttle-size: The amount of modules that may be published at once (defaults to 25)
- --throttle-delay: How long to wait after a module was successfully published (defaults to 30 seconds)

This is usefull to avoid errors/retries when publishing to rate-limited repositories on huge monorepos:

`bash
lerna publish from-git --throttle --throttle-delay=$((3600*24))
`

$3

`sh
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.

Per-Package Configuration

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

$3

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

`json
"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.

$3

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

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

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

$3

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

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

- Passing --dist-tag will _overwrite_ this value.
- This value is _always_ ignored when --canary is passed.

$3

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.

`json
"publishConfig": {
"directory": "dist"
}
`

NPM Provenance

NPM provenance is a security feature that creates a verifiable connection between a published package and its source code repository. When enabled, it provides cryptographic proof that a package was built from a specific GitHub repository commit using GitHub Actions or Gitlab runners. This helps prevent supply chain attacks where malicious actors could publish compromised versions of popular packages.

You can enable Provenance via .npmrc or within the workflow
- in .npmrc via provenance=true
- or in the workflow via env: NPM_CONFIG_PROVENANCE: true

For more detailed informations on how to enable the feature and use this in a CI environment like GitHub Action Workflow, you can read this article that I wrote:
- How to publish on npm with --provenance using Lerna-Lite

OIDC

Using OIDC trusted publishing with Lerna-Lite

Lerna-Lite adds support for OIDC trusted publishing, which is a solution developed by npm to secure the publishing process and not use traditional tokens or other fixed credentials.

The key idea is that your package(s) can be configured on the npm side to be required to be published from within a specific trusted environment such as GitHub Actions or GitLab CI.

Within these supported environments, the OIDC token is retrieved and used to publish the package instead of a user or automation token.

If you follow the official guidance from npm on how to configure your pipelines, then it will also just work for Lerna-Lite, no additional configuration is needed.

https://docs.npmjs.com/trusted-publishers

You can see a fully working example repo here: https://github.com/lerna-lite-test/oidc

publishConfig Overrides

- bin, browser, cpu, esnext, es2015, exports, imports, libc, main, module, os, type, types, typings, typesVersions, umd:main, unpkg

> Note the code implementation was copied from pnpm but it is totally agnostic and will work the same way for all package manager (pnpm, yarn or npm).

> Note this option is enabled by default but can be disabled via lerna publish --no-publish-config-overrides or ("publishConfigOverrides": false in lerna.json)

For instance, the following package.json (with pnpm, yarn or npm):

`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:

`json
{
"name": "foo",
"version": "1.0.0",
"main": "lib/index.js",
"typings": "lib/index.d.ts"
}
`

Lifecycle Scripts

`js
// 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

catalog: protocol

The catalog: protocol (pnpm catalogs, Bun catalogs or Yarn catalogs) can be recognized by Lerna-Lite. When publishing, they will be replaced "as is" by reading and using the version range defined in your global catalog(s). If you need to bump the version of a package in a catalog, you will need to edit your root config (e.g pnpm-workspace.yaml) manually. If for whatever reasons, you wish them to be bumped automatically, then we strongly suggest that you rather use the workspace: protocol instead of catalog which is better suited for local workspace dependencies.

> [!NOTE]
> Lerna-Lite only has a read access to the catalog and will pull all dependency versions it finds from your pnpm-workspace.yaml (or package.json) catalog, but it will never write back to that file. If you want version bump while running lerna version/publish commands, then you should use workspace: for local dependencies. A side note though, it does work with local dependencies but only if the local dependency version changed in a previous git commit before lerna commands are executed (since again Lerna-Lite will never write or update the catalog).

So for example, if our pnpm-workspace.yaml (or package.json > workspaces) file has the following configuration

from a pnpm-workspace.yaml

`yaml
packages:
- packages/*

Define a catalog of version ranges.

or from project root package.json > workspaces

`json
{
"name": "my-monorepo",
"workspaces": {
"packages": ["packages/*"],
"catalog": {
"fs-extra": "^11.2.0",
"typescript": "^5.7.0"
},
"catalogs": {
"react17": {
"react": "^17.0.0",
"react-dom": "^17.0.0"
},
"react18": {
"react": "^18.2.0",
"react-dom": "^18.2.0"
}
}
}
}
`

and then if one of our monorepo package have the following dependencies defined in our package.json

`json
{
"dependencies": {
"fs-extra": "catalog:"
},
"devDependencies": {
"typescript": "catalog:"
},
"peerDependencies": {
"react": "catalog:react18",
"react-dom": "catalog:react18"
}
}
`

#### versions that will be published

Lerna-Lite will resolve all catalog: protocol by extracting the version ranges defined in the global catalog(s) and will publish the following:

`json
{
"dependencies": {
"fs-extra": "^11.2.0"
},
"devDependencies": {
"typescript": "^5.7.0"
},
"peerDependencies": {
"react": "^18.2.0",
"react-dom": "^18.2.0"
}
}
`

workspace: protocol

The workspace: protocol (pnpm workspace, yarn workspace) is also supported by Lerna-Lite. You could also 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:

- the corresponding version in the target workspace (if you use workspace:*, workspace:~, or workspace:^)
- the associated semver range (for any other range type)

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:

`json
{
"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.

#### versions that will be published

The library is doing a strict match and it will transform and publish the following:

`json
{
"dependencies": {
"foo": "1.5.0",
"bar": "~1.5.0",
"qar": "^1.5.0",
"zoo": "^1.5.0"
}
}
`

> Note semver range with an operator (ie workspace:>=2.0.0) are also supported but will never be mutated.

FAQ

$3

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.