@lerna/version

What is @lerna/version?

@lerna/version is a part of the Lerna monorepo management toolset. It is specifically used for versioning packages within a monorepo. This package helps in managing the versioning of multiple packages in a monorepo, ensuring that all packages are correctly versioned and updated.

What are @lerna/version's main functionalities?

Bump Version

This command bumps the version of the packages in the monorepo. It updates the version in the package.json files and creates a new git commit and tag.

lerna version

Independent Versioning

This command allows each package in the monorepo to have its own version, rather than a single version for the entire repository.

lerna version --independent

Conventional Commits

This command uses conventional commit messages to determine the version bump for each package. It automates the versioning based on the commit history.

lerna version --conventional-commits

Pre-release Versions

This command creates a pre-release version with the specified identifier (e.g., beta, alpha). It is useful for releasing versions that are not yet stable.

lerna version --preid beta

Other packages similar to @lerna/version

semantic-release

semantic-release automates the versioning and package publishing process based on the commit messages. It ensures that the version number is correctly incremented and the package is published to the registry. Unlike @lerna/version, which is focused on monorepos, semantic-release can be used with any repository.

standard-version

standard-version is a tool for versioning and changelog generation based on conventional commit messages. It is similar to @lerna/version in that it helps manage versioning, but it is not specifically designed for monorepos.

changesets

changesets is a tool for managing versioning and changelogs in monorepos. It provides a workflow for creating changesets that describe the changes made, which are then used to determine the version bumps. It is similar to @lerna/version but offers a more flexible and detailed approach to managing changes in a monorepo.

README

@lerna/version

Bump version of packages changed since the last release

Usage

lerna version 1.0.1 # explicit
lerna version patch # semver keyword
lerna version       # select from prompt(s)

When run, this command does the following:

1. Identifies packages that have been updated since the previous tagged release.
2. Prompts for a new version.
3. Modifies package metadata to reflect new release, running appropriate lifecycle scripts in root and per-package.
4. Commits those changes and tags the commit.
5. Pushes to the git remote.

Positionals

semver bump

lerna version [major | minor | patch | premajor | preminor | prepatch | prerelease]
# uses the next semantic version(s) value and this skips `Select a new version for...` prompt

When this positional parameter is passed, lerna version will skip the version selection prompt and increment the version by that keyword. You must still use the --yes flag to avoid all prompts.

Prerelease

If you have any packages with a prerelease version number (e.g. 2.0.0-beta.3) and you run lerna version with and a non-prerelease bump (major, minor, or patch), it will publish those previously pre-released packages as well as the packages that have changed since the last release.

For projects using conventional commits, use the following flags for prerelease management:

• --conventional-prerelease: release current changes as prerelease versions.
• --conventional-graduate: graduate prerelease versioned packages to stable versions.

Running lerna version --conventional-commits without the above flags will release current changes as prerelease only if the version is already in prerelease.

Options

• @lerna/version
  • Usage
  • Positionals
    • semver bump
  • Prerelease
  • Options
    • --allow-branch <glob>
    • --amend
    • --changelog-preset
    • --conventional-commits
    • --conventional-graduate
    • --conventional-prerelease
    • --create-release <type>
    • --exact
    • --force-publish
    • --git-remote <name>
    • --ignore-changes
    • --ignore-scripts
    • --include-merged-tags
    • --message <msg>
    • --no-changelog
    • --no-commit-hooks
    • --no-git-tag-version
    • --no-granular-pathspec
    • --no-private
    • --no-push
    • --preid
    • --sign-git-commit
    • --sign-git-tag
    • --force-git-tag
    • --tag-version-prefix
    • --yes
  • Deprecated Options
    • --cd-version
    • --repo-version
    • --skip-git
  • Tips
    • Generating Initial Changelogs
  • Lifecycle Scripts

--allow-branch <glob>

A whitelist of globs that match git branches where lerna version is enabled. It is easiest (and recommended) to configure in lerna.json, but it is possible to pass as a CLI option as well.

{
  "command": {
    "version": {
      "allowBranch": "main"
    }
  }
}

With the configuration above, the lerna version will fail when run from any branch other than main. It is considered a best-practice to limit lerna version to the primary branch alone.

{
  "command": {
    "version": {
      "allowBranch": ["main", "feature/*"]
    }
  }
}

With the preceding configuration, lerna version will be allowed in any branch prefixed with feature/. Please be aware that generating git tags in feature branches is fraught with potential errors as the branches are merged into the primary branch. If the tags are "detached" from their original context (perhaps through a squash merge or a conflicted merge commit), future lerna version executions will have difficulty determining the correct "diff since last release."

It is always possible to override this "durable" config on the command-line. Please use with caution.

lerna version --allow-branch hotfix/oops-fix-the-thing

--amend

lerna version --amend
# commit message is retained, and `git push` is skipped.

When run with this flag, lerna version will perform all changes on the current commit, instead of adding a new one. This is useful during Continuous integration (CI) to reduce the number of commits in the project's history.

In order to prevent unintended overwrites, this command will skip git push (i.e., it implies --no-push).

--changelog-preset

lerna version --conventional-commits --changelog-preset angular-bitbucket

By default, the changelog preset is set to angular. In some cases you might want to change either use a another preset or a custom one.

Presets are names of built-in or installable configuration for conventional changelog. Presets may be passed as the full name of the package, or the auto-expanded suffix (e.g., angular is expanded to conventional-changelog-angular).

This option is can also be specified in lerna.json configuration:

{
  "changelogPreset": "angular"
}

If the preset exports a builder function (e.g. conventional-changelog-conventionalcommits), you can specify the preset configuration too:

{
  "changelogPreset": {
    "name": "conventionalcommits",
    "issueUrlFormat": "{{host}}/{{owner}}/{{repository}}/issues/{{id}}"
  }
}

--conventional-commits

lerna version --conventional-commits

When run with this flag, lerna version will use the Conventional Commits Specification to determine the version bump and generate CHANGELOG.md files.

Passing --no-changelog will disable the generation (or updating) of CHANGELOG.md files.

--conventional-graduate

lerna version --conventional-commits --conventional-graduate=package-2,package-4

# force all prerelease packages to be graduated
lerna version --conventional-commits --conventional-graduate

When run with this flag, lerna version will graduate the specified packages (comma-separated) or all packages using *. This command works regardless of whether the current HEAD has been released, similar to --force-publish, except that any non-prerelease packages are ignored. If changes are present for packages that are not specified (if specifying packages), or for packages that are not in prerelease, those packages will be versioned as they normally would using --conventional-commits.

"Graduating" a package means bumping to the non-prerelease variant of a prerelease version, eg. package-1@1.0.0-alpha.0 => package-1@1.0.0.

NOTE: when specifying packages, dependents of specified packages will be released, but will not be graduated.

--conventional-prerelease

lerna version --conventional-commits --conventional-prerelease=package-2,package-4

# force all changed packages to be prereleased
lerna version --conventional-commits --conventional-prerelease

When run with this flag, lerna version will release with prerelease versions the specified packages (comma-separated) or all packages using *. Releases all unreleased changes as pre(patch/minor/major/release) by prefixing the version recommendation from conventional-commits with pre, eg. if present changes include a feature commit, the recommended bump will be minor, so this flag will result in a preminor release. If changes are present for packages that are not specified (if specifying packages), or for packages that are already in prerelease, those packages will be versioned as they normally would using --conventional-commits.

--create-release <type>

lerna version --conventional-commits --create-release github
lerna version --conventional-commits --create-release gitlab

When run with this flag, lerna version will create an official GitHub or GitLab release based on the changed packages. Requires --conventional-commits to be passed so that changelogs can be generated.

To authenticate with GitHub, the following environment variables can be defined.

• GH_TOKEN (required) - Your GitHub authentication token (under Settings > Developer settings > Personal access tokens), please give it repo:public_repo scope when create the token.
• GHE_API_URL - When using GitHub Enterprise, an absolute URL to the API.
• GHE_VERSION - When using GitHub Enterprise, the currently installed GHE version. Supports the following versions.

To authenticate with GitLab, the following environment variables can be defined.

• GL_TOKEN (required) - Your GitLab authentication token (under User Settings > Access Tokens).
• GL_API_URL - An absolute URL to the API, including the version. (Default: https://gitlab.com/api/v4)

NOTE: When using this option, you cannot pass --no-changelog.

--exact

lerna version --exact

When run with this flag, lerna version will specify updated dependencies in updated packages exactly (with no punctuation), instead of as semver compatible (with a ^).

For more information, see the package.json dependencies documentation.

--force-publish

lerna version --force-publish=package-2,package-4

# force all packages to be versioned
lerna version --force-publish

When run with this flag, lerna version will force publish the specified packages (comma-separated) or all packages using *.

This will skip the lerna changed check for changed packages and forces a package that didn't have a git diff change to be updated.

--git-remote <name>

lerna version --git-remote upstream

When run with this flag, lerna version will push the git changes to the specified remote instead of origin.

--ignore-changes

Ignore changes in files matched by glob(s) when detecting changed packages.

lerna version --ignore-changes '**/*.md' '**/__tests__/**'

This option is best specified as root lerna.json configuration, both to avoid premature shell evaluation of the globs and to share the config with lerna diff and lerna changed:

{
  "ignoreChanges": ["**/__fixtures__/**", "**/__tests__/**", "**/*.md"]
}

Pass --no-ignore-changes to disable any existing durable configuration.

In the following cases, a package will always be published, regardless of this option:

1. The latest release of the package is a prerelease version (i.e. 1.0.0-alpha, 1.0.0–0.3.7, etc.).
2. One or more linked dependencies of the package have changed.

--ignore-scripts

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

--include-merged-tags

lerna version --include-merged-tags

Include tags from merged branches when detecting changed packages.

--message <msg>

This option is aliased to -m for parity with git commit.

lerna version -m "chore(release): publish %s"
# commit message = "chore(release): publish v1.0.0"

lerna version -m "chore(release): publish %v"
# commit message = "chore(release): publish 1.0.0"

# When versioning packages independently, no placeholders are replaced
lerna version -m "chore(release): publish"
# commit message = "chore(release): publish
#
# - package-1@3.0.1
# - package-2@1.5.4"

When run with this flag, lerna version will use the provided message when committing the version updates for publication. Useful for integrating lerna into projects that expect commit messages to adhere to certain guidelines, such as projects which use commitizen and/or semantic-release.

If the message contains %s, it will be replaced with the new global version version number prefixed with a "v". If the message contains %v, it will be replaced with the new global version version number without the leading "v". Note that this placeholder interpolation only applies when using the default "fixed" versioning mode, as there is no "global" version to interpolate when versioning independently.

This can be configured in lerna.json, as well:

{
  "command": {
    "version": {
      "message": "chore(release): publish %s"
    }
  }
}

--no-changelog

lerna version --conventional-commits --no-changelog

When using conventional-commits, do not generate any CHANGELOG.md files.

NOTE: When using this option, you cannot pass --create-release.

--no-commit-hooks

By default, lerna version will allow git commit hooks to run when committing version changes. Pass --no-commit-hooks to disable this behavior.

This option is analogous to the npm version option --commit-hooks, just inverted.

--no-git-tag-version

By default, lerna version will commit changes to package.json files and tag the release. Pass --no-git-tag-version to disable the behavior.

This option is analogous to the npm version option --git-tag-version, just inverted.

--no-granular-pathspec

By default, lerna version will git add only the leaf package manifests (and possibly changelogs) that have changed during the versioning process. This yields the equivalent of git add -- 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 add -- .. By opting into this pathspec, you MUST HAVE ALL SECRETS AND BUILD OUTPUT PROPERLY IGNORED, OR IT WILL BE COMMITTED AND PUSHED.

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

--no-private

By default, lerna version will include private packages when choosing versions, making commits, and tagging releases. Pass --no-private to disable this behavior.

Note that this option does not exclude private scoped packages, only those with a "private": true field in their package.json file.

--no-push

By default, lerna version will push the committed and tagged changes to the configured git remote. Pass --no-push to disable this behavior.

--preid

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

lerna version prepatch --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 version will increment premajor, preminor, prepatch, or prerelease semver bumps using the specified prerelease identifier.

--sign-git-commit

This option is analogous to the npm version option of the same name.

--sign-git-tag

This option is analogous to the npm version option of the same name.

--force-git-tag

This option replaces any existing tag instead of failing.

--tag-version-prefix

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

Keep in mind that currently you have to supply it twice: for version command and for publish command:

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

--yes

lerna version --yes
# skips `Are you sure you want to publish these packages?`

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

Deprecated Options

--cd-version

Pass the semver keyword to the bump positional instead.

--repo-version

Pass an explicit version number to the bump positional instead.

--skip-git

Use --no-git-tag-version and --no-push instead.

NOTE: This option does not restrict all git commands from being executed. git is still required by lerna version.

Tips

Generating Initial Changelogs

If you start using the --conventional-commits option after the monorepo has been active for awhile, you can still generate changelogs for previous releases using conventional-changelog-cli and lerna exec:

# Lerna does not actually use conventional-changelog-cli, so you need to install it temporarily
npm i -D conventional-changelog-cli
# Documentation: `npx conventional-changelog --help`

# fixed versioning (default)
# run in root, then leaves
npx conventional-changelog --preset angular --release-count 0 --outfile ./CHANGELOG.md --verbose
npx lerna exec --concurrency 1 --stream -- 'conventional-changelog --preset angular --release-count 0 --commit-path $PWD --pkg $PWD/package.json --outfile $PWD/CHANGELOG.md --verbose'

# independent versioning
# (no root changelog)
npx lerna exec --concurrency 1 --stream -- 'conventional-changelog --preset angular --release-count 0 --commit-path $PWD --pkg $PWD/package.json --outfile $PWD/CHANGELOG.md --verbose --lerna-package $LERNA_PACKAGE_NAME'

If you use a custom --changelog-preset, you should change --preset value accordingly in the example above.

Lifecycle Scripts

// preversion:  Run BEFORE bumping the package version.
// version:     Run AFTER bumping the package version, but BEFORE commit.
// postversion: Run AFTER bumping the package version, and AFTER commit.

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

1. Detect changed packages, choose version bump(s)
2. Run preversion lifecycle in root
3. For each changed package, in topological order (all dependencies before dependents):
   1. Run preversion lifecycle
   2. Update version in package.json
   3. Run version lifecycle
4. Run version lifecycle in root
5. Add changed files to index, if enabled
6. Create commit and tag(s), if enabled
7. For each changed package, in lexical order (alphabetical according to directory structure):
   1. Run postversion lifecycle
8. Run postversion lifecycle in root
9. Push commit and tag(s) to remote, if enabled
10. Create release, 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.