lerna-lite
Lerna-Lite 
Lerna-Lite is a lighter version of the original Lerna
- About Lerna-Lite
- Getting Started
- How It Works
- Installation
- Project Demo - See it in Action
- README Badge
lerna.jsonconfig file- Contributions
- Troubleshooting
- Sponsors
Available Commands
Click on any command below to see documentation of all available options
- 🛠️
init- creates a new Lerna-Lite workspace structure and addslerna.json - 🕜 changed - list local packages changed since last release -
npm i @lerna-lite/changed -D - 🌓 diff - git diff all packages since the last release -
npm i @lerna-lite/diff -D - 👷 exec - execute shell commands in each workspace package -
npm i @lerna-lite/exec -D - 📖 list - list local packages -
npm i @lerna-lite/list -D - ☁️ publish - publish workspace packages -
npm i @lerna-lite/publish -D - 📑 version - bump workspace package versions -
npm i @lerna-lite/version -D - 🏃 run - run npm script in each workspace package -
npm i @lerna-lite/run -D - 👓 watch - watch for changes & execute commands when fired -
npm i @lerna-lite/watch -D
Note since the
publishpackage depends on theversionpackage, you could simply install@lerna-lite/publishto automatically get access to both commands.
📢 Lerna-Lite supports pnpm/yarn workspace: protocol and pnpm catalog: protocol
Take 30sec. to complete this 1 question poll survey 🔘 if you are using this feature. It's a simple poll to find out which package manager is the most popular with workspace: protocol feature (so far, about 60% pnpm and 40% yarn).
Lerna-Lite itself is also using both pnpm catalogs and pnpm workspaces 🎉
Who is using Lerna-Lite
Here are some of the largest projects using Lerna-Lite
Jest
|
React Navigation
|
Format.JS
|
Volar
|
Blueprint
|
NativeScript
License
About Lerna-Lite
Lerna-Lite differs from the original Lerna since it only has a limited subset of its original commands (which itself has 15 commands) and they are all optional in Lerna-Lite making its install footprint a lot smaller. Lerna was originally built as an all-in-one tool, however nowadays Workspaces are available in all package managers and the need for an all-in-one tool, which includes built-in workspaces functionalities (like bootstrap), is no longer necessary. Lerna-Lite is built around this new reality and is only providing commands that package managers do not include. To summarize, Lerna-Lite is more modular than the original Lerna and you'll end up installing a lot less dependencies while also making it more versatile to use with other tools like TurboRepo, pnpm and others...
Lerna-Lite assumes, and requires you to pre-setup your Workspace through your favorite package manager (npm, pnpm, yarn) that will take care of the symlinks. Lerna-Lite does not include Lerna's bootstrap, add, create or link commands hence the need for you to properly setup your workspace prior to installing Lerna-Lite.
According to your needs, choose the best option to setup a workspace: npm 7+ | Yarn classic | Yarn 2+ | pnpm
Why create this lib/fork?
Below are the main reasons as to why this fork was created:
- Lerna's repo was unmaintained for nearly 2 years (in early 2022, Lerna's dependencies were really out of date)
- Lerna (original) got later transferred to Nrwl, the company behind Nx, and are now the current maintainers
- please note that Lerna-Lite fork was created couple months before Nrwl took over Lerna
- we also replicate all Lerna PRs whenever possible (except for
Nxspecific changes which are ignored)
- Lerna (original) got later transferred to Nrwl, the company behind Nx, and are now the current maintainers
- A desire to create a smaller and lighter alternative compared to the original all-in-one Lerna tool
- Lerna-Lite is entirely modular, every commands are totally optional (install only what you need).
- The project was rewritten in TypeScript with ESM-only since v2.0 (you can still use it in a CJS environment)
- The original Lerna version v5.5+ now requires Nx (want it or not), but that is not the case in Lerna-Lite
- note, if you already use
Nxthen it's probably better to use Lerna, otherwise Lerna-Lite is a better alternative - if you use tools like TurboRepo and install the original Lerna, you end up installing 2 similar tools (not good)
- note, if you already use
- in Lerna-Lite we also added a few unique features which are not available in Lerna (original):
catalog:protocol support for bothversionandpublishcommands (new)workspace:protocol support- Lerna added support for the same feature 6 months later in their v6.0 release
- --dry-run to preview version/publish & changelogs locally (will show git changes without committing them)
- lerna version --allow-peer-dependencies-update to also update your peer dependencies
- lerna version --changelog-header-message "msg" for showing banner or sponsors in your changelogs
- lerna version --changelog-include-commits-client-login to add PR contributors in GitHub releases
- lerna publish --remove-package-fields (remove certain fields from
package.jsonbefore publishing) - lerna version --skip-bump-only-releases to avoid cluttering your GitHub releases with
independentmode - lerna version --sync-workspace-lock to sync lock file before publishing (not needed w/
workspace:protocol)- ie: we use it in here to publish Lerna-Lite without any
scriptsordevDependencies
- ie: we use it in here to publish Lerna-Lite without any
On a final note, I think that the best feature of Lerna-Lite (versus Lerna) really has to be its modularity. A large portion of the users are only interested in version/publish commands, but on the other hand, a small minority might want other commands like lerna run/exec. Lerna-Lite offers this kind of flexibility by allowing the user to choose what to install (see installation below) which help to keep your download to the bare minimum.
Lerna-Lite will help you with the following:
Note all commands are optional in Lerna-Lite, refer to the Available Commands table for more info
Version and Publish commands
- Automate the creation of new Versions (
independentorfixedversion) of all your workspace packages.- it will automatically Commit/Tag your new Version & create new GitHub/GitLab Release (when enabled).
- Automate, when enabled, will create Changelogs for all packages by reading your Conventional Commits.
- Automate, the repository Publishing of your new version(s) for all your packages (on NPM or other platforms).
Other optional commands
- Changed command, when installed, will list all local packages that have changed since the last tagged release
- Diff command, when installed, will show git diff of all packages or a single package since the last release
- Exec command, when installed, will help you execute shell commands in parallel and in topological order.
- List command, when installed, will list all workspace local packages
- Run command, when installed, will help you run npm script in parallel and in topological order.
- Watch command, when installed, will watch for changes within all packages and execute certain commands
README Badge
[](https://github.com/lerna-lite/lerna-lite)Getting Started
Let's start by installing Lerna-Lite CLI as a dev dependency to your project and then run the init command to get started (see init#readme for all options). Note that the CLI must be installed at all time, then proceed by installing any other optional commands (the CLI is only including the init command), refer to the Available Commands table for more info.
# install Lerna-Lite CLI locally or globally (`init` is the only command installed)
$ npm install -g @lerna-lite/cli # pnpm add -g @lerna-lite/cli
# create your monorepo and initialize lerna-lite
$ mkdir lerna-repo
$ cd lerna-repo
$ npx lerna init # OR pnpm exec lerna init
# for npm/yarn (only) workspaces add --use-workspaces
$ npx lerna init --use-workspacesThis will create a lerna.json configuration file as well as a packages folder, so your folder should now look like this:
lerna-repo/
packages/
package-a
package.json
lerna.jsonNote Lerna-Lite now supports 3 file extension types (.json, .jsonc and .json5), however not all code editors support JSON Schema with .json5, so lerna.json might still be the preferred extension (all formats support inline comments, even .json).
Note that package-a will not be created, it is only shown here to help clarify the structure. For more info and full details about the lerna.json file, you can read the lerna.json Wiki. Also note that you can optionally add comments to your lerna.json config file since it is also able to parse JSON5 file format.
The final step will be to install the commands that are of interest to you (publish, version, run, exec, ...)
$ npm i @lerna-lite/publish -DHow It Works
Lerna allows you to manage your project using one of two modes: Fixed or Independent.
Fixed/Locked mode (default)
Fixed mode Lerna projects operate on a single version line. The version is kept in the lerna.json file at the root of your project under the version key. When you run lerna publish, if a module has been updated since the last time a release was made, it will be updated to the new version you're releasing. This means that you only publish a new version of a package when you need to.
Note: If you have a major version zero, all updates are considered breaking. Because of that, running
lerna publishwith a major version zero and choosing any non-prerelease version number will cause new versions to be published for all packages, even if not all packages have changed since the last release.
This is the mode that Jest) is currently using. Use this if you want to automatically tie all package versions together. One issue with this approach is that a major change in any package will result in all packages having a new major version.
Independent mode
lerna init --independent
Independent mode Lerna projects allows maintainers to increment package versions independently of each other. Each time you publish, you will get a prompt for each package that has changed to specify if it's a patch, minor, major or custom change.
Independent mode allows you to more specifically update versions for each package and makes sense for a group of components. Combining this mode with something like semantic-release would make it less painful. (There is work on this already at atlassian/lerna-semantic-release).
Set the
versionkey inlerna.jsontoindependentto run in independent mode.
Installation
Lerna-Lite is entirely modular, as opposed to Lerna, and installing the CLI locally or globally will only provide you the
initcommand. Please make sure to install other commands that you are interested in (see table below).
If you are new to Lerna-Lite, you could also run the lerna init command which will create the lerna.json for you with a minimal structure setup. If you are using a client other than npm, then make sure to update the npmClient property in lerna.json (for example: "npmClient": "yarn" or "pnpm").
Note please make sure that you have a
lerna.jsonconfig file in your project root and in it aversionproperty defined with either a fixed orindependentmode. Otherwise, an error will be thrown if you're missing any of them.
Usage
The basic usage is to add either custom NPM scripts or simply run the commands in your shell with the Lerna-Lite CLI. See below for basic Lerna npm script samples.
// package.json / npm scripts
"scripts": {
"new-version": "lerna version",
"new-publish": "lerna publish from-package",
"preview:new-version": "lerna version --dry-run",
"run-tests": "lerna run test",
}JSON Schema
You can add the $schema property into your lerna.json to take advantage of Lerna-Lite JSON Schema (lerna init can help setting it up for you). This will help with the developer experience, users will be able to see what properties are valid with their types and a brief description of what each option does (descriptions are pulled from their associated lerna command options documentation).
lerna.json
{
"$schema": "node_modules/@lerna-lite/cli/schemas/lerna-schema.json",
// ...
// or from GitHub CDN
"$schema": "https://raw.githubusercontent.com/lerna-lite/lerna-lite/main/packages/cli/schemas/lerna-schema.json",
}Note JSON Schema might not be well supported by all code editors with
.json5, uselerna.jsonif that is a problem for you.
Separate / Optional Installs
Click on any command below to see documentation of all available options
| Command | Install | Description |
|---|---|---|
| ☁️ publish | npm i @lerna-lite/publish -D |
publish each workspace package |
| 📑 version | npm i @lerna-lite/version -D |
create new version for each workspace package |
| 🕜 changed | npm i @lerna-lite/changed -D |
list local packages changed since last release |
| 🌓 diff | npm i @lerna-lite/diff -D |
git diff all packages since the last release |
| 👷 exec | npm i @lerna-lite/exec -D |
execute an command in each workspace package |
| 📖 list | npm i @lerna-lite/list -D |
list local packages |
| 🏃 run | npm i @lerna-lite/run -D |
run npm script in each workspace package |
| 👓 watch | npm i @lerna-lite/watch -D |
watch for changes & execute commands when fired |
Note since the
publishpackage depends on theversionpackage, you could simply install@lerna-lite/publishto automatically gain access to both commands.
Migration for existing Lerna users
Migrating from the original Lerna, should be fairly easy since you simply need to replace your Lerna dependency with Lerna-Lite @lerna-lite/cli, and also install the command(s) that you are interested in and that's about it. The CLI commands and options are nearly identical. The biggest difference compared to Lerna is that you need to manually choose and install the commands that you are interested in as shown below:
Note as opposed to Lerna v7 and higher, the
useWorkspaceis not enabled by default in Lerna-Lite and we still recommend to use eitheruseWorkspacesfor Yarn/NPM or use the defaultpackagesinlerna.jsonfor pnpm users. TheuseWorkspaceshas some drawback since some of the packages could be unrelated to the project releases (ie: website, examples) and for this use case thepackages/*defined inlerna.jsonis a better approach (i.e. Jest uses this approach).
- remove Lerna from your local & global dependencies
npm uninstall lerna # OR yarn remove lerna -W
npm uninstall -g lerna # OR yarn global remove lerna- install Lerna-Lite CLI, note this will only provide you the
initcommand
# Lerna CLI (only includes `init`)
npm install @lerna-lite/cli -D- then install any of the optional Lerna-Lite command(s) that you wish to use (
changed,diff,exec,list,run,publish,versionand/orwatch) refer to Available Commands table above
# for example, let's install publish (note publish will automatically provide you the `version` command since it's a dependency)
npm install @lerna-lite/publish -D- review your
lerna.jsonconfig file and remove any unrelated old command options, for examplebootstrapdoes not exist in Lerna-Lite so there's no need to keep that config`diff { "npmClient": "yarn", "command": {"version": { "conventionalCommits": true }, - "bootstrap": {
- "npmClientArgs": ["--no-package-lock"]
- }
}
}
`Note after switching to Lerna-Lite and publishing your next release with conventional-changelog, you will probably see a lot of diff changes across your
changelog.mdfiles, a lot of empty lines will be deleted, and that is totally expected since Lerna-Lite has code in place to remove these unnecessary empty lines.
Project Demo?
You want to see a project demo? Sure... you're looking at it 😉
Yes indeed, this project was originally created as an NPM Workspace and later migrated to a pnpm workspaces for the sole purpose of demoing and testing its own code. All changelogs and versions are created and published by the lib itself, how sweet is that? You can also see that this project has its own lerna.json config file as well to run properly (take a look to see how it works).
See it in Action 🎦
You can see a small video of a new version release on this Release Demo - Wiki to demonstrate its usage. Are you confused with all these options? Perhaps taking a look at some of the references shown below might help you get started.
Great Lerna Tutorials / References
- Release Demo - Wiki - Lerna-Lite demo (animated gif)
- How to Use Lerna - YouTube video
- Lerna Release Workflow - GitHub Template
Contributions
Contributions are very well encouraged. Also please note that the original code was created by much smarter persons than myself and so my knowledge of the project might still lack in some areas of the project. The main goal of this fork was mainly to make it more modular and keep dependencies up to date (Renovate was put in place and is running frequently).
Development / Contributions
To contribute to the project, please follow the steps shown in the Contributing Guide
Troubleshooting
If you have problems running the project and your problems are related to Git commands that were executed, we then suggest to first try with the --dry-run option to see if it helps in finding the error(s) that you may have. Another great, and possibly much more useful suggestion, is to search in the original Lerna issues list and see if any solution could help you (remember that Lerna-Lite is a fork of the original code from Lerna and it works the same way). Lastly, if that is not enough and you wish to troubleshoot yourself, then read this Troubleshooting - Wiki to possibly troubleshoot yourself the execution in your own environment.
Published Packages
| Package Name | Version | NPM Downloads | Description | Changes |
|---|---|---|---|---|
| @lerna-lite/cli |  |
 |
Lerna-Lite CLI | changelog |
| @lerna-lite/core |  |
 |
Lerna-Lite core functions | changelog |
| @lerna-lite/init |  |
 |
Lerna-Lite setup | changelog |
| @lerna-lite/publish |  |
 |
Publish workspace packages | changelog |
| @lerna-lite/version |  |
 |
Bump Version & Changelogs | changelog |
| @lerna-lite/exec |  |
 |
Execute shell commands in repo | changelog |
| @lerna-lite/changed |  |
 |
List changes since last release | changelog |
| @lerna-lite/diff |  |
 |
Diff changes since last release | changelog |
| @lerna-lite/list |  |
 |
List local packages | changelog |
| @lerna-lite/listable |  |
 |
Listable utils for list, changed |
changelog |
| @lerna-lite/npmlog |  |
 |
inline version of npmlog util |
changelog |
| @lerna-lite/profiler |  |
 |
internal profiler | changelog |
| @lerna-lite/run |  |
 |
Run npm scripts in workspace | changelog |
| @lerna-lite/watch |  |
 |
Watch changes in workspace | changelog |
Sponsors
Thanks to all my sponsors!
