@lerna/legacy-package-management

@lerna/legacy-package-management

This package contains the legacy lerna add, lerna bootstrap and lerna link commands which deal with things better handled by your package manager npm/yarn/pnpm.

This package can be thought of as being in maintenance mode only - no new features will be considered for legacy package management concerns, and we will only look to merge critical patches and security updates.

See below for full context as to why this exists.

Background

Lerna is the original monorepo/workspace tool in the JavaScript ecosystem. When it was created in 2015/2016 the ecosystem looked totally different, and there were no built in capabilities to handle working with multiple packages in a single repository (a "workspace"). Commands like lerna bootstrap, lerna add and lerna link were all a critical part of the lerna project, because there were no other options.

However, now that we find ourselves in 2023, the fact is that - for many years now - the package managers we know and love (npm, yarn and pnpm) all fully support that concept of workspaces as a first-class use-case.

They have battle tested implementations covering adding, removing and linking local packages, and combining them with third party dependencies in a natural way.

This is the reason why, for the past several years of his tenure as lead maintainer of Lerna @evocateur has been encouraging folks to strongly reconsider their use of the legacy package management commands in lerna, and instead leverage their package manager of choice to do what it does best.

We on the Nx Team knew about this context from afar, but as new stewards of the project we did not want to jump straight in and start removing capabilities without first taking the time to get familiar with the reality up close. Now that we have been actively maintaining the project for half a year, we are in full agreement with Daniel and others that the legacy package management commands in lerna need to be retired.

By removing these legacy pieces which have better alternatives natively in package managers, we and the rest of the lerna community will be freed up to concentrate our efforts on things which are uniquely valuable about lerna (such as, but not limited to, versioning and publishing), and making them the best they can be!

We of course want to make sure that folks who are perhaps less aware of the modern capabilities of their package manager are not left confused by this change, so we will be building out comprehensive migration guides on https://lerna.js.org to help them transition their thinking from a legacy lerna command to its equivalent for npm, yarn or pnpm.

Changelog

7.0.0 (2023-06-08)

BREAKING CHANGES

After updating we strongly recommend running lerna repair in your project. This will migrate your lerna.json to the latest and greatest and remove any outdated options.

As this is a major release there are a few breaking changes to be aware of, which may or may not affect your lerna repos, depending on how you are using the tool.

• node v14 support is dropped because it is end of life

When a node version because end of life (EOL) it means that it does not receive any updates or maintenance whatsoever, even if critical security vulnerabilities have been uncovered.

We strongly encourage all folks here to keep up with the maintenance LTS version of Node at an absolute minimum:

https://github.com/nodejs/release#release-schedule

NOTE: Due to an oversight, we initially forgot to formally remove this from the engines field. This was corrected in patch 7.3.1

• legacy package management commands have been removed

We no longer include the bootstrap, add, and link commands by default. We strongly recommend using your package manager (npm, yarn, pnpm) for package management related concerns such as installing and linking dependencies.

There will not be any active work done on these commands and you should look to migrate as soon as possible.

For full context how why we made this change and how you can migrate your projects, please read our detailed guide here: https://lerna.js.org/docs/legacy-package-management

• Workspaces are used by default and useWorkspaces has been removed

We now use your package manager's workspaces configuration by default in order to resolve packages for lerna to operate on. If you wish to customize the packages that lerna will operate on, you can still use a packages property in your lerna.json just as you did before, but there is no longer any need for a useWorkspaces flag. If the packages property is present, lerna will use that, otherwise it will try and read your workspaces configuration.

Running lerna repair will automatically remove useWorkspaces from your lerna.json for you.

NOTE: If you are using pnpm as your package manager, it is important to set "npmClient": "pnpm" in your lerna.json so that lerna knows to look for a pnpm-workspaces.yaml file and not just check your root package.json.

• lerna init can no longer be run on an existing lerna repo

It was a confusing behavior that lerna init could be run on an existing lerna repo and would attempt to coerce its setup to something closer to a fresh repo, so we have removed this behavior and lerna will hard error if it detects the directory is already initialized.

You can run lerna repair at any time to update your configuration to the latest and greatest.

• long deprecated options have been removed

The following options (on the left of the => in each case) have been deprecated for many years (since before we took over stewardship of the project) and have finally been removed. If you are using them in your lerna.json all you need to do is run lerna repair and it will automatically migrate you to their modern equivalent. If you are passing them in on the command line, you will need to update your usage as follows:

• --includeFilteredDependencies => --includeDependencies
• --includeFilteredDependents => --includeDependents
• --githubRelease => --createRelease=github
• --skipGit => --push=false --gitTagVersion=false
• --repoVersion => [positional bump]
• --cdVersion => [positional bump]
• --npmTag => --distTag
• --ignore => --ignoreChanges

Features

• add migration for adding $schema, increase some strictness (73ceac3)
• publish: support custom directory per-package (#3699) (9da575e)
• init: support --dryRun flag and preview file system changes

Bug Fixes

• bump cosmiconfig to v8 (#3701) (898923d)
• ensure repair command not blocked by config validation (e237d58)
• improve github client missing env var error (ce4b352)
• internal cli.js should not be bundled (53d73c6)
• migration building/publishing issues (27bf800)
• publish: use correct version in log messages (#3702) (4be9188)
• share project data when nesting commands (#3709) (53e71e4)
• support nx 16.3.1+ (#3707) (647dbb5)