Lerna-Lite is a super light version of the original Lerna
- About Lerna-Lite
- Getting Started
- Project Demo - See it in Action
- README Badge
lerna.jsonconfig file- Contributions
- Troubleshooting
- Commands
- included with CLI
- optional commands (requires separate install, refer to the installation table shown below)
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 this new workspace: protocol feature. Thanks
Lerna-Lite itself is now also using pnpm workspaces with the workspace: protocol as well 🎉
Here are some of the largest projects using the Lerna-Lite fork
Jest
|
Format.JS
|
Vee-Validate
|
Standard Notes
|
Lerna-Lite differs from the original Lerna since it only has a limited subset of commands from Lerna, which itself has 15 commands, while Lerna-Lite only includes half of them (and a few of them are optional). 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, is no longer necessary. Lerna-Lite is built around this new reality and its CLI is only including the minimum commands which are init, info, publish and version, while other commands are available as optional and separate installation (exec, list, run, ...). In summary, Lerna-Lite is more modular than the original Lerna and so you'll end up installing less dependencies, this also makes it more versatile to use with other tools like Turborepo, pnpm and others...
As a summary, Lerna-Lite assumes, and requires to pre-setup a Workspace through your favorite package manager (npm, pnpm, yarn) that will take care of the symlinks (Lerna-Lite does not include the bootstrap, neither link commands hence the need for a workspace pre-setup), so make sure that your workspace is properly setup before installing Lerna-Lite.
For more info on how to setup a workspace, choose the best option for you: npm 7+ / Yarn classic / Yarn 2+ / pnpm
Mainly for the following reasons:
- original Lerna repo was unmaintained for nearly 2 years (dependencies were out of date)
- this is no longer true since Nrwl took over stewardship of Lerna (we now keep PRs in sync with them when possible), but the next few points are still valid
- a desire to create a smaller and more modular lib that is lighter than the original all-in-one Lerna
- it's smaller since we only copied half of Lerna's commands and many of them are totally optional.
- we don't need
bootstrapanymore since Workspaces are supported by all package managers. - also the main goal of this fork was to keep only
versionandpublishcommands in the core and make everything else as optional packages (choose and install what you really need).
- rewrite the lib in TypeScript for type checking and to be compatible with ESM in the future
- replicate a few opened PRs (fixes and features) from Lerna and also add extra features in Lerna-Lite
- for example we support yarn/pnpm
workspace:protocol, we added changelog headers, and addeddry-runoptions
- for example we support yarn/pnpm
- Lerna v5-6 is installing Nx as a required dependency, want it or not, while it remains optional in Lerna-Lite
- Lerna v5-6 is also enforcing
useWorkspacesoption to be enabled, but this can have undesired effects (you might want to track only thepackagesfolder with Lerna and not other folders likedemoorwebsite). Again, that will not be enforced in Lerna-Lite, in fact it's the opposite, I personally prefer to just usepackagesinlerna.json(especially with pnpm)
- Automate the rolling of new Versions (
independentorfixed) of all your workspace packages.- it will automatically Commit/Tag your new Version & create new GitHub/GitLab Release (when enabled).
- Automate the creation of Changelogs for all your packages by reading all Conventional Commits and a merged one in the project root.
- Automate the repository Publishing of your new version for all your packages (NPM or other platforms).
- 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.
[](https://github.com/ghiscoding/lerna-lite)Let's start by installing Lerna as a dev dependency of your project and run the init command to get started (see init#readme for all options).
$ mkdir lerna-repo
$ cd lerna-repo
$ npx lerna init # with pnpm
# 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.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.
Run the following commands to install Lerna-Lite in your project and/or install it globally by adding the -g option.
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").
You can add the $schema property into your lerna.json to take advantage of Lerna-Lite JSON Schema (lerna init will automatically configure this for you). This will help with the developer experience, users will be able to see what properties are valid with a brief description of what they do (pulled from each lerna command options documentation).
{
"$schema": "node_modules/@lerna-lite/cli/schemas/lerna-schema.json",
// ...
}npm i @lerna-lite/cli -D -WMinimum CLI install to get started with Lerna-Lite, that will give you access to the following list of commands:
| Command | Description |
|---|---|
| 🛠️ init | create/initialize a new Lerna-Lite repo |
| 💻 info | print local environment information |
| 📑 version | create new version for each workspace package |
| ☁️ publish | publish each workspace package |
Note: Lerna-Lite CLI is only including 4 built-in commands by default (shown in table above), all other commands are optional commands and must be installed separately as shown in the table below.
| Command | Install | Description |
|---|---|---|
| 🕜 changed | npm i @lerna-lite/changed -D -W |
list local packages changed since last release |
| 🌓 diff | npm i @lerna-lite/diff -D -W |
git diff all packages since the last release |
| 👷 exec | npm i @lerna-lite/exec -D -W |
execute an command in each workspace package |
| 📖 list | npm i @lerna-lite/list -D -W |
list local packages |
| 🏃 run | npm i @lerna-lite/run -D -W |
run npm script in each workspace package |
Add custom NPM Scripts or simply run the commands in a shell with Lerna-Lite CLI, below are a few very simple demo scripts.
// package.json / npm scripts
"scripts": {
"new-version": "lerna version",
"new-publish": "lerna publish from-package",
"exec-echo": "lerna exec echo hello", // optional `exec` command
"run-tests": "lerna run test", // optional `run` command
}Migration for existing Lerna Users
If you are migrating from Lerna, it should be fairly easy to just replace Lerna with Lerna-Lite in your dependencies and that's about it, the CLI commands are the same, take a look at the quick steps shown below:
- remove Lerna from your local & global dependencies
npm uninstall lerna -W # OR yarn remove lerna -W
npm uninstall -g lerna # OR yarn global remove lerna- install Lerna-Lite CLI to get access to
init,info,versionandpublishcommands
# Lerna CLI (includes `init`, `info`, `version` and `publish` commands)
npm install @lerna-lite/cli -D -W- optionally install
changed,diff,exec,listand/orruncommands (refer to installation table)
# install any of the optional commands (refer to installation table)
npm install @lerna-lite/run -D -WYou want to see a project demo? Sure, you're looking at it 😉
Yes indeed, this lib was originally created as an NPM Workspace and later changed to a pnpm workspaces for the sole purpose of demoing and testing its own code. All changelogs and published versions are created and published by the lib itself, how sweet is that? You will also find that Lerna-Lite project has its own lerna.json config file 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.
- Release Demo - Wiki - Lerna-Lite demo (animated gif)
- How to Use Lerna - YouTube video
- Lerna Release Workflow - GitHub Template
Feel free to contribute any Pull Request. Also please note that I'm just a simple developer & user of this lib, the same as you are, my knowledge of the library is also limited but together we can make it better.
If you wish to contribute to the project, please follow these steps:
Note: this project uses pnpm workspaces, you can install pnpm by following their installation or simply run npx pnpm to run any of the pnpm scripts shown below:
- clone the lib:
git clone https://github.com/ghiscoding/lerna-lite
- install with pnpm from the root:
pnpm installORnpx pnpm install
- run a full TypeScript (TSC) build
pnpm buildORnpx pnpm build
- add/run Jest unit tests (make sure to run the previous steps first):
pnpm jest(full test coverage)pnpm jest:watch(watch mode)
- you can also troubleshoot/debug via the VSCode debugger launch configs that were setup for each command
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) 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 in your own environment.
| Package Name | Version | Description | Changes |
|---|---|---|---|
| @lerna-lite/cli |  |
Lerna-Lite Init/Info/Version/Publish comands CLI | changelog |
| @lerna-lite/core |  |
Lerna-Lite core & shared methods (internal use) | changelog |
| @lerna-lite/info |  |
Print local environment information | changelog |
| @lerna-lite/init |  |
create a new Lerna-Lite repo | 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/run |  |
Run npm scripts in current workspace | changelog |
| @lerna-lite/optional-cmd-common |  |
Lerna-Lite common utils for optional commands Exec/List/Run (internal use) | changelog |