Subset of Lerna in a smaller & more modular project. Helps manage and publish multiple packages in a monorepo/workspace structure
lerna.json
config file
init
- creates a new Lerna-Lite workspace structure and adds lerna.json
init
) included with the CLI
changed
- list local packages that changed since last tagged releasediff
- git diff all packages or a single package since the last releaseexec
- execute shell command in each workspace packagelist
- list local packagespublish
- publish every workspace packages that changedversion
- create new version for each workspace packagesrun
- run npm script, in topological order, in each workspace packagewatch
- watch for changes within packages and execute commandsworkspace:
protocolTake 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 this new workspace:
protocol feature (so far, about 60% pnpm and 40% yarn).
Lerna-Lite itself is also using pnpm workspaces with the workspace:
protocol 🎉
Here are some of the largest projects using Lerna-Lite
Jest | React Navigation | Format.JS | Volar | Blueprint | NativeScriptLerna-Lite differs from the original Lerna since it only has a limited subset of Lerna's list of commands (which itself has 15 commands) and all commands are optional in Lerna-Lite making installs typically much 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 needed. 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 also making it more versatile to use with other tools like TurboRepo, pnpm and other...
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 the bootstrap
, add
, create
and link
commands hence the need for you to properly setup your workspace prior to installing Lerna-Lite.
For more info on how to setup a workspace, choose the best option: npm 7+ | Yarn classic | Yarn 2+ | pnpm
Below are the main reasons as to why this fork was created:
workspace:
protocol support (*) Lerna added support for the same 6 months later in v6independent
modeworkspace:
protocol)package.json
before publishing)
scripts
and devDependencies
On a final note, the best feature of Lerna-Lite (versus Lerna) 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 are only interested in other commands like run/exec. Lerna-Lite offers this flexibility by allowing the user to choose what to install (see installation below). Lastly from the list above, the number 5 could be a concern for some users who are not interested to use Nx (like me) but still want to have the power of Lerna with updated dependencies and keep their download to the bare minimum.
Note all commands are optional in Lerna-Lite, refer to the Installation table for more info
independent
or fixed version) of all your workspace packages.
[![lerna--lite](https://img.shields.io/badge/maintained%20with-lerna--lite-e137ff)](https://github.com/lerna-lite/lerna-lite)
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 Installation 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-workspaces
This 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.json
Note 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 config.
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.
Finally install the commands that are of interest to you (publish
, version
, run
, exec
, ...)
$ npm i @lerna-lite/publish -D
Lerna-Lite is entirely modular, as opposed to Lerna, and installing the CLI locally or globally will only provide you the
init
command. 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 setup. If you are using a different 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.json
config file created and aversion
property defined with either a fixed orindependent
mode. An error will be thrown if you're missing any of them.
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 a 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.json
if that is a problem for you.
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
publish
package depends on theversion
package, you could simply install@lerna-lite/publish
to automatically gain access to both commands.
Add custom NPM scripts or simply run the commands in your shell with the Lerna-Lite CLI, you can see below some very 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",
}
Migrating from the original Lerna, should be fairly easy since you simply need to replace your Lerna dependency with Lerna-Lite @lerna-lite/cli
, then install all the commands that you are interested in and that's it. The CLI commands and options are the same. The biggest difference compared to Lerna is that you need to install the commands that you are interested in, for that take a look at the steps shown below:
Note as opposed to Lerna v7 and higher, the
useWorkspace
is not enabled by default in Lerna-Lite and we still recommend to use eitheruseWorkspaces
for Yarn/NPM or use the defaultpackages
inlerna.json
for pnpm users. TheuseWorkspaces
has 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.json
could be better (i.e. Jest uses this approach).
npm uninstall lerna # OR yarn remove lerna -W
npm uninstall -g lerna # OR yarn global remove lerna
init
command# Lerna CLI (includes `init`)
npm install @lerna-lite/cli -D
changed
, diff
, exec
, list
, run
, publish
, version
and/or watch
)
refer to installation table above
# for example, let's install publish (note publish will automatically give you version since it's a dependency)
npm install @lerna-lite/publish -D
lerna.json
config file and remove any unrelated command options, for example bootstrap
does not exist in Lerna-Lite so there's no need to keep that config{
"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.md
files, many empty lines will be deleted, and that is totally expected since Lerna-Lite has code in place to remove these empty lines that were added by Lerna for no reason.
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).
You can see a small video of a new version release on this Release Demo - Wiki to demonstrate its usage. Confused with all these options? Perhaps taking a look at some of the references shown below might help you get started.
Feel free to contribute any Pull Request. Also please note that the original code was not created by me and my knowledge of the library is still limited in some sections of the project. The main goal of this fork was to make it more modular and keep dependencies up to date (Renovate was put in place and runs weekly).
To contribute to the project, please follow the steps shown in the Contributing Guide
If you have problems running the lib and your problems are related to Git commands that were executed, then we 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.
Package Name | Version | Description | Changes |
---|---|---|---|
@lerna-lite/cli | Lerna-Lite CLI required to execute any command | changelog | |
@lerna-lite/core | Lerna-Lite core & shared methods (internal use) | changelog | |
@lerna-lite/init | Setup your monorepo to use Lerna-Lite | changelog | |
@lerna-lite/publish | Publish packages in the current workspace | changelog | |
@lerna-lite/version | Bump Version & write Changelogs | changelog | |
@lerna-lite/exec | Execute shell command in current workspace | changelog | |
@lerna-lite/changed | List local packages that changed since last release | changelog | |
@lerna-lite/diff | Diff all packages or a single package since last release | changelog | |
@lerna-lite/list | List local packages | changelog | |
@lerna-lite/listable | Listable utils used by list and changed commands (internal use) |
changelog | |
@lerna-lite/filter-packages | Lerna-Lite filtering package utils used by optional commands (internal use) | changelog | |
@lerna-lite/profiler | Lerna-Lite Profiler used by some optional commands (internal use) | changelog | |
@lerna-lite/run | Run npm scripts in current workspace | changelog | |
@lerna-lite/watch | Watch for changes within packages and execute commands | changelog |