reggi/lerna-tutorial

:dragon: A basic description of how to use Lerna

Lerna tutorial

TLDR;

• npm install (installs lerna)

• lerna bootstrap (connects all the packages)

• npm -C ./packages/usage run start (console logs "alpha" and "beta" from combind use example module)

• Tree Structure

• packages

  • alpha (deps: [])
  • beta (deps: [])
  • usage (deps: ["alpha", "beta"])

Summary

First off, What is lerna? lerna is a tool that allows you to maintain multiple npm packages within one repository.

There's a couple of benefits to this kind of approach, the paradigm is called a monorepo, and more can be read about it from the source of babel, and react.

Here's the gist:

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

Getting started.

For this demo I'm going to be using [email protected]. lerna is a CLI (command line interface) tool. You're going to want to install it with the --global (-g) flag.

npm i [email protected] -g

Then once it's done installing your going to want to run the following

mkdir my-monorepo && cd $_ && lerna init

This will do a couple of things.

• Creating packages folder.
• Updating package.json.
• Creating lerna.json.

The /packages folder is where all of your packages belong. Let's go about making a new package alpha.

cd packages
mkdir alpha
cd alpha
npm init -y
echo "module.exports = 'alpha'" > index.js

Lets go through the same steps for another package beta.

First go up one directory:

cd ..

Now go about creating beta.

mkdir beta
cd beta
npm init -y
echo "module.exports = 'beta'" > index.js

Now we're going to create a usage package that uses both alpha and beta as dependencies.

First go up one directory:

cd ..

Now go about creating \usage.

mkdir usage
cd usage
npm init -y
touch index.js

Open up /packages/usage/index.js in a text editor and paste this in.

var alpha = require('alpha')
var beta = require('beta')
console.log(alpha + " " + beta)

We're almost there. At this point your whole project should look something like this:

.
├── README.md
├── lerna.json
├── package.json
└── packages
    ├── alpha
    │   ├── index.js
    │   └── package.json
    ├── beta
    │   ├── index.js
    │   └── package.json
    └── usage
        ├── index.js
        └── package.json

What you want to do now is go into /packages/usage/package.json and add these lines under dependencies.

{
  "dependencies": {
    "alpha": "1.0.0",
    "beta": "1.0.0"  
  }
}

Now you need to wire everything up with this command.

lerna bootstrap

The output from this command should look something like this:

Lerna v2.0.0-beta.20
Linking all dependencies
Successfully bootstrapped 3 packages.

Now using the tree command once more (brew install tree) we can see the folder structure we can see what lerna did.

.
├── README.md
├── lerna.json
├── package.json
└── packages
    ├── alpha
    │   ├── index.js
    │   ├── node_modules
    │   └── package.json
    ├── beta
    │   ├── index.js
    │   ├── node_modules
    │   └── package.json
    └── usage
        ├── index.js
        ├── node_modules
        │   ├── alpha
        │   │   ├── index.js
        │   │   └── package.json
        │   └── beta
        │       ├── index.js
        │       └── package.json
        └── package.json

It added two stubbed (my term not lerna's) modules. If you peak inside /packages/usage/node_modules/alpha/index.js you can see what I mean.

contents of ./packages/usage/node_modules/alpha/index.js

module.exports = require("/Users/thomas/Desktop/lerna-tutorial/packages/alpha");

Note: This is an absolute path to the module. So if you ever move your lerna project you'll need to rerun lerna bootstrap.

And voila! When we run node ./packages/usage/index.js we get our expected output!

alpha beta

lerna-tutorial's Issues

:)

hi sure:)

Does this work with lerna 2.8? Followed things exactly but lerna is bootstraping 0 modules

How can I consume particular package in app?

[This is not an issue, just a clarification]

Say, in the list of packages my application is only interested in particular package.
In my app's package.json should I include entire URL for the package lerna-tutorial/packages/usage ?
Or there is any other smarter way of doing this ?

Note : All my packages are local to my team, and I am not uploading them to npm.

how do I add a dependency

Thanks for the tutorial.

I have scripted the entire process in powershell. But when I try to add a dependency to one of the packages I get

G:\git\tft\test\packages\app [master +4 ~0 -0 !]             
λ  yarn add typescript --dev                                 
yarn add v0.21.3                                             
info No lockfile found.                                      
[1/4] Resolving packages...                                  
Couldn't find any versions for "beta" that matches "1.0.0"   
? Please choose a version from this list: (Use arrow keys)   
Couldn't find any versions for "alpha" that matches "1.0.0"  
? Please choose a version from this list: (Use arrow keys)   
> 0.0.9                                                      
  0.0.8                                                      
  0.0.7                                                      
  0.0.6                                                      
  0.0.4                                                      
  0.0.3                                                      
  0.0.2                                                      
  0.0.1                                                      

How are we supposed to add dependencies?