• About Lerna-Lite
  • Why create this lib/fork?
• Getting Started
  • Installation
  • JSON Schema
  • Migration for existing Lerna users
• Project Demo - See it in Action
• README Badge
• lerna.json config file
• Contributions
• Troubleshooting
• Available Commands, they are all optional, refer to the Installation table shown below
  • 🛠️ init - creates a new Lerna-Lite workspace structure and adds lerna.json
    • the only command included with the CLI is init
  • 📑 version - create new version for each workspace packages
  • ☁️ publish - publish every workspace packages that changed
  • 🕜 changed - list local packages that changed since last tagged release
  • 🌓 diff - git diff all packages or a single package since the last release
  • 👷 exec - execute shell command in each workspace package
  • 📖 list - list local packages
  • 🏃 run - run npm script, in topological order, in each workspace package
  • 👓 watch - watch for changes within packages and execute commands

Watch for file changes within packages and execute commands from the root of the repository. This solves a common problem for package-based monorepos, which is to trigger rebuilds of packages when their files changed. Head over to the lerna watch documentation for more details.

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

React Navigation

Format.JS

Volar

Standard Notes

MIT License

Lerna-Lite differs from the original Lerna since it only has a limited subset of Lerna's list of commands (which itself has 15 commands), while Lerna-Lite only includes half of them and all commands 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 needed. Lerna-Lite is built around this new reality and only provides 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, this also makes 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 the bootstrap, add, create and link commands hence the need for a workspace pre-setup), so make sure that your workspace is properly setup before adding Lerna-Lite.

For more info on how to setup a workspace, choose the best option for you: npm 7+ / Yarn classic / Yarn 2+ / pnpm

Below are the main reasons as to why this fork was created:

1. Lerna repo was unmaintained for nearly 2 years (in early 2022, dependencies were really out of date)
   • this is no longer the case since Nrwl, the company behind Nx, took over stewardship of Lerna
     • please note that Lerna-Lite fork was created couple months before Nrwl took over Lerna
     • we now try to replicate Lerna's PRs into Lerna-Lite when possible
2. a desire to create a smaller and more modular project that is lighter than the original all-in-one Lerna
   • Lerna-Lite is now entirely modular, all commands are optional (install only what you use)
3. rewrite the lib in TypeScript and build the project as ESM only (you can still use it in a CommonJS environment)
4. replicate a few opened PRs from Lerna and add extra features into Lerna-Lite
5. Lerna is becoming another Nx product (Lerna >=5.5 is now requiring Nx while it's not in Lerna-Lite)
   • if you use Nx then it's probably better to stick with Lerna, but if you aren't then Lerna-Lite is preferred
6. Lastly a few extra features were added, and only exist, into Lerna-Lite:
   • workspace: protocol support (Lerna added support for it six months later in v6)
   • --dry-run to preview version/publish changes and changelogs
   • lerna version --changelog-header-message "msg" it could be used to add sponsor badges in changelogs
   • lerna version --changelog-include-commits-client-login to add PR contributors
   • lerna version --allow-peer-dependencies-update if you want your peer deps to also be updated
   • lerna version --skip-bump-only-release to avoid cluttering your GitHub releases in independent mode
   • lerna publish --remove-package-fields (empty certain fields from package.json before publishing, ie: Lerna-Lite uses it to remove 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 run/exec commands. Lerna-Lite offers that flexibility by allowing you to install only what you use and are interested in (see installation below).

Note all commands are optional in Lerna-Lite, refer to the Installation table for more info

• Automate the creation of new Versions (independent or fixed version) of all your workspace packages.
  • it will automatically Commit/Tag your new Version & create new GitHub/GitLab Release (when enabled).
• Automate, when enabled, the creation of Changelogs for all your packages by reading all Conventional Commits.
• Automate, the repository Publishing of your new version(s) for all your packages (on 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.
• Watch command, when installed, will watch for changes within all packages and execute certain commands

[![lerna--lite](https://img.shields.io/badge/maintained%20with-lerna--lite-e137ff)](https://github.com/lerna-lite/lerna-lite)

Let's start by installing the 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 and then other commands must be installed separately (the CLI only includes the init command), refer to the Installation table for more info.

# install Lerna-Lite CLI locally or globally (only includes `init` command)
$ 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
$ lerna init

# for npm/yarn (only) workspaces add --use-workspaces
$ 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 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.

Finally install the commands that are of interest to you (publish, version, run, exec, ...)

$ npm i @lerna-lite/publish -D -W

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 that are of interest (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 a version property defined with either a fixed or independent 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 will automatically configure this 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 they do (each description are pulled from their associated lerna command options documentation).

{
  "$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 since the publish package depends on the version package, you could simply install @lerna-lite/publish to automatically give you access to the version command.

Add custom NPM Scripts or simply run the commands in your shell with the Lerna-Lite CLI, you can see some very basic script samples below.

// package.json / npm scripts
"scripts": {
  "new-version": "lerna version",
  "new-publish": "lerna publish from-package",
  "run-tests": "lerna run test",        // optional `run` command
}

If you are migrating from Lerna, it should be fairly easy to just replace Lerna with Lerna-Lite in your dependencies and install necessary commands and that's about it. The CLI commands and options are the same, but all commands are optional installs, take a look at the quick steps shown below:

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

2. install Lerna-Lite CLI which will provide you the init command (only)

# Lerna CLI (includes `init`)
npm install @lerna-lite/cli -D -W

3. finally install the Lerna-Lite command(s) that you wish to use (changed, diff, exec, list, run, publish, version and/or watch) refer to installation table above

# install any of the optional commands (refer to installation table)
npm install @lerna-lite/publish -D -W

Note you might see a lot of diff changes across your changelog.md files after switching to Lerna-Lite and that is totally expected since Lerna-Lite has code in place to remove empty lines that were added by Lerna for no real 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 Lerna-Lite 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.

• 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 in some areas of the project, 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:

1. clone the lib:
   • git clone https://github.com/lerna-lite/lerna-lite
2. install with pnpm from the root:
   • pnpm install OR npx pnpm install
3. run a full TypeScript (TSC) build
   • pnpm build OR npx pnpm build
4. add/run Vitest unit tests (make sure to run the previous steps first):
   • pnpm test (watch mode)
   • pnpm test:coverage (full test coverage)
5. 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 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