Lerna Tutorial - Managing Monorepos with Lerna

Background

Lerna is a tool that allows you to maintain multiple npm packages within one repository. There are multiple benefits of using such an approach - one repo, multiple packages. This paradigm is called monorepo (mono - single, repo - repository). You can read more about monorepo -

• https://github.com/babel/babel/blob/master/doc/design/monorepo.md

To summarise pros are -

• Single lint, build, test and release process.
• Easy to coordinate changes across modules. 
• A single place to report issues.
• Easier to set up a development environment.
• Tests across modules are run together which finds bugs that touch multiple modules easier.

Now that you understand what a monorepo is, let's come back to Lerna. Lerna is a tool that helps you manage your monorepos. In this post, I am going to show you a complete tutorial of how you can use lerna to manage a custom multi package repo that we will create.

Lerna Tutorial -  Managing Monorepos with Lerna

First of all, you need to install lerna. Lerna is a CLI. To install it you need to execute following command -

• npm install --global lerna

This should install lerna in your local machine globally. You can run the following command to check the version of lerna installed -

• lerna -v

 For me, it's 3.4.1 at the time of writing this post. Now let's create a directory for our lerna demo project.  Let's call it lerna-demo. You can create it with the following command -

• mkdir lerna-demo 

Now navigate inside this directory

• cd lerna-demo

Now execute following command -

• lerna init

This should create a basic structure of monorepo. Take a look at below picture to understand it's structure.

 It does following things -

1. Creates packages folder. All packages go under this.
2. Creates package.json at the root. This defines global dependencies. It has the dependency on lerna by default.
3. Creates lerna.json at the root. This identifies lerna repo root.

 Now let's go to packages folder and start creating our packages. We will then see how we can link them and use. So navigate to packages directory.

• cd packages

Package - AdditionModule

Let's create a package that takes care of addition. Let's call it AdditionModule. Create a directory for this inside packages folder and execute following commands -

• mkdir AdditionModule 
• cd AdditionModule 
• npm init -y

This should create a file called package.json inside AdditionModule directory. Now in the same folder create a file called index.js in the same folder and add following content to it -

module.exports.add = function(x,y){
    return x + y;
}

Save the file. This basically exposes add method to any other package that would have a dependency on this. Your 1st package is done. Let's create one more package for subtraction.

Package - SubtractionModule

 Run similar commands inside packages folder -

• mkdir SubtractionModule
• cd SubtractionModule
• npm init -y

 Now in SubtractionModule folder create a file called index.js and add following code to it -

module.exports.subtract = function(x,y){
    return x - y;
}

Save the file. This basically exposes subtract method to any other package that would have a dependency on this. Now let's create a package that would have a dependency on  AdditionModule and SubtractionModule and can use add and subtract functions.

Package - Calc

Our final package - let's call it Calc would have a dependency on  AdditionModule and SubtractionModule packages. So let's create the package 1st -

• mkdir Calc
• cd Calc
• npm init -y

Now create a file called index.js and add following content to it -

var add = require('AdditionModule');
var subtract = require('SubtractionModule');

var sum = add.add(2,3);
var diff = subtract.subtract(3,2);

console.log("Sum: " + sum + " Diff: " + diff);

Save the file. Now open package.json to add our dependencies. Edit package.json to add following content to it -

  "dependencies": {
      "AdditionModule": "1.0.0",
      "SubtractionModule": "1.0.0"
   },

So your entire package.json looks like -

{
  "name": "Calc",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
      "AdditionModule": "1.0.0",
      "SubtractionModule": "1.0.0"
   },
}

Now you are all set up. Your directory structure should look like below -

Now it's time to use lerna to link packages. Go to lerna-demo directory and execute the following command -

• lerna bootstrap

 This should do all linking for you. It would create node_modules directory in Calc package and add symlinks to AdditionModule and SubtractionModule. Your directory structure would now look like -

Now you can simply run calc index.js as follows -

• node packages/Calc/index.js

And you should get expected output -

The important thing was the linking part that lerna does for you so that you do not have to worry about it.


For complete details on all available commands see - https://github.com/lerna/lerna

Related Links

• What is the purpose of Node.js module.exports and how do you use it?(OSFG) 
• https://github.com/lerna/lerna