Integrating Nx and Lerna

In case you missed it, Nrwl, the company behind Nx, took over stewardship of Lerna. This opens up a range of new opportunities for integrating the two. Continue reading to learn more.

Lerna does three main things:

  • managing dependencies (lerna bootstrap)
  • running commands for a single or multiple packages (lerna run)
  • publish your packages, including version management and changelog generation (lerna publish)

A common pain point with Lerna is when it comes to scaling monorepos. This is where Nx shines.

Speed up Lerna with Nx's powerful task scheduler

Nx comes with a powerful task scheduler that intelligenty runs operations and makes sure they are quick. This happens in a variety of ways:

  • Parallelization and task dependencies - Nx automatically knows how your projects relate to each other. As a result, if project-a depends on project-b and you run the build command for project-a, Nx first runs the builds for all of project-a's dependencies and then the invoked project itself. Nx sorts these tasks to maximize parallelism.
  • Only run what changed - Using Nx affected commands you only really execute tasks on the projects that changed, compared to a given baseline (usually the main branch).
  • Caching - You get Nx's computaton caching for free. All operations, including artifacts and terminal output are restored from the cache (if present) in a completely transparent way without disrupting your DX. No configuration needed. Obviously this results in an incredible speed improvement.
  • Distributed Task Execution - This is unique to Nx. In combination with Nx Cloud your tasks are automatically distributed across CI agents, taking into account build order, maximizing parallelization and thus agent utilization. It even learns from previous runs to better distribute tasks! Learn more

Add Nx to an existing Lerna monorepo

Nx can be added to an existing Lerna monorepo by running the following command:

npx add-nx-to-monorepo

This will

  1. Add Nx to your package.json.
  2. Create nx.json, containing all the necessary configuration for Nx.
  3. Set up Nx Cloud (if you chose "yes").

You can then run your package's npm scripts by simply invoking

nx <command> <package-name>

Hence, if package myproj has a build script, you can just run it using nx build myproj. Similarly for running tests use nx test myproj and so on.

Here's an overview of some more Lerna commands and the corresponding Nx version:

1{
2  "private": true,
3  "scripts": {
4-   "build:all": "lerna run build",
5+   "build:all": "nx run-many --target=build --all",
6-   "build:app1": "lerna run build --scope=app1",
7+   "build:app1": "nx build app1",
8-   "build:since": "lerna run build --since=main",
9+   "build:since": "nx affected --target=build",
10-   "test:all": "lerna run test",
11+   "test:all": "nx run-many --target=test --all",
12-   "test:app1": "lerna run test --scope=app1",
13+   "test:app1": "nx test app1",
14-   "test:since": "lerna run test --since=main",
15+   "test:since": "nx affected --target=test",
16-   "dev": "lerna run dev --stream --parallel",
17+   "dev": "nx run-many --target=dev --all",
18-   "dev:app1": "lerna run dev --stream --scope=app1",
19+   "dev:app1": "nx dev app1"
20  },
21  "devDependencies": {
22    "lerna": "3.*",
23+   "nx": "latest"
24  }
25}

Learn more about the Nx CLI.

Dependency Management

Nx does not handle dependency management. You can continue using lerna bootstrap if that suits your needs or switch to newer options such as using built-in features of Yarn/NPM/PNPM workspaces.

Publishing

Lerna has an integrated publishing process with version management and changelog generation. Nx doesn't handle publishing, quite contrary. The Nx repository itself uses Lerna for the package publishing process. So feel free to coninue using it!

That said, you can also easily integrate other tools such as changesets or release-it (just to mention two).

What's more?

Nx comes with a whole range of additional features such as:

  • Interactive workspace visualization - to interactively explore the underlying project graph for understanding dependencies and find paths between nodes.
  • Nx plugins - for adding first-class support for React, Next.js, React Native, Angular, Node, NestJS, Jest, Cypress, Storybook and many more.
  • Dedicated VSCode extension - You can install Nx Console which is a dedicated VSCode extension to provide a visual interface for navigating your monorepo workspace in terms of launching commands as well as for generating code.
  • GitHub integration - Install the Nx Cloud Github App to get inline reporting on your CI jobs.
  • ...

But take your time to explore.