Skip to content

Latest commit

 

History

History
247 lines (177 loc) · 23.3 KB

README.md

File metadata and controls

247 lines (177 loc) · 23.3 KB
Raw

Lerna-Lite 🐉

License: MIT PR TypeScript lerna--lite

Actions Status codecov jest NPM downloads npm

Lerna-Lite is a super light version of the original Lerna

If a command that you wish to use is missing, simply reach out and we could potentially add it as an optional command. However please note that the following commands (bootstrap and link) are totally out of the picture.

📢 Lerna-Lite now supports pnpm/yarn workspace: protocol

Are you using this new feature? Please take 30sec. to fill in this 1 question poll survey 🔘 to see which package manager is the most popular and how many of you are taking advantage of this new workspace: protocol. Thanks

Lerna-Lite itself is now also using pnpm workspaces with the workspace: protocol as well, woohoo 🎉

We also strongly suggest that you use the new opt-in flag --sync-workspace-lock to automatically update your lock file 🔒.

License

MIT License

About Lerna-Lite

Lerna-Lite differs from the original Lerna in the sense that 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 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 only includes the minimum commands which are init, info, publish and version, while other commands are available (exec, list and run) they are totally optional and you won't download them unless you choose to do so. In summary, Lerna-Lite is more modular than the original Lerna and with this small change, you'll end up with less dependencies to download and install, this also make 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: Yarn classic / Yarn 2+ / pnpm / npm 7+

Why create this lib/fork?

Mainly for the following reasons:

  1. original Lerna repo was no longer maintained (dependencies were out of date)
    • this is no longer true since Nrwl took over ownership of Lerna, but the next few points are still valid
  2. wanted to create a smaller lib that is more modular than the original Lerna
    • it's smaller since we only copied half of Lerna's commands and a few are totally optional.
    • we don't need all of Lerna's packages anymore since Workspaces are now supported by all package managers.
    • the main goal of this fork was to keep only version and publish commands in the core and make everything else as optional packages (install and use only what you need).
  3. rewrite the lib in TypeScript
  4. replicate a few opened PRs (fixes and features) from Lerna and also add extra features in Lerna-Lite
    • for example we now support the workspace: protocol and dry-run options

This lib will help you with

Version and Publish commands (included with the CLI)

  • Automate the rolling of new Versions (independent or fixed) 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.
    • each package will get its own Changelog and a merged Changelog will also be created in the root.
  • Automate the repository Publishing of your new version for all your packages (NPM or other platform).

Other useful, but optional, commands

  • Changed command, when installed, will list all local packages that have changed since the last tagged 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.

README Badge

Using Lerna-Lite? Add a README badge to show it off: lerna--lite

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

Getting Started

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 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 that package-a will not be created, it is only shown 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.

Installation

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. 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").

Command Install Description Included
🛠️ init npm i @lerna-lite/cli -D -W create/initialize a new Lerna-Lite repo Yes
💻 info npm i @lerna-lite/cli -D -W print local environment information Yes
📑 version npm i @lerna-lite/cli -D -W create new version for each workspace package Yes
☁️ publish npm i @lerna-lite/cli -D -W publish each workspace package Yes
🕜 changed npm i @lerna-lite/changed -D -W list local packages changed since last release Optional
🌓 diff npm i @lerna-lite/diff -D -W git diff all packages since the last release Optional
👷 exec npm i @lerna-lite/exec -D -W execute an command in each workspace package Optional
📖 list npm i @lerna-lite/list -D -W list local packages Optional
🏃 run npm i @lerna-lite/run -D -W run npm script in each workspace package Optional

Note: the default lerna CLI is including only 4 built-in commands (init,info,publish,version), all other commands are optional commands and must be installed separately as shown in the table.

Usage

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:

  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
  1. install Lerna-Lite CLI to get access to init, info, version and publish commands
# Lerna CLI (includes `init`, `info`, `version` and `publish` commands)
npm install @lerna-lite/cli -D -W
  1. optionally install changed, exec, list and/or run commands (refer to installation table)
# install any of the optional commands (refer to installation table)
npm install @lerna-lite/run -D -W

Project Demo?

You 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).

See it in Action 🎦

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.

Good Lerna Tutorials / References

Contributions

Feel free to contribute any Pull Request, PRs are very welcome. 👷👷‍♀️

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 probably similar to yours but together we can make it better (and lighter).

Development / Contributions

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/ghiscoding/lerna-lite
  2. install with pnpm:
    • pnpm install OR npx pnpm install
  3. run a full TypeScript (TSC) build
    • pnpm build OR npx pnpm build
  4. add/run Jest unit tests (make sure to run the previous steps first):
    • pnpm jest (full test coverage)
    • pnpm jest:watch (watch mode)
  5. you can also troubleshoot/debug via the VSCode debugger launch configs that were setup for each command

Troubleshooting

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 --git-dry-run (or --cmd-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.

Lerna-Lite Full List of Packages

Package Name Version Description Changes
@lerna-lite/cli npm Lerna-Lite Init/Info/Version/Publish comands CLI changelog
@lerna-lite/core npm Lerna-Lite core & shared methods (internal use) changelog
@lerna-lite/info npm Print local environment information changelog
@lerna-lite/init npm create a new Lerna-Lite repo changelog
@lerna-lite/publish npm Publish packages in the current workspace changelog
@lerna-lite/version npm Bump Version & write Changelogs changelog
@lerna-lite/exec npm Execute shell command in current workspace changelog
@lerna-lite/changed npm List local packages that changed since last release changelog
@lerna-lite/diff npm Diff all packages or a single package since the last release changelog
@lerna-lite/list npm List local packages changelog
@lerna-lite/listable npm Listable utils used by list and changed commands changelog
@lerna-lite/run npm Run npm scripts in current workspace changelog
@lerna-lite/optional-cmd-common npm Lerna-Lite common utils for optional commands Exec/List/Run (internal use) changelog