Lerna Tutorial Series: Brief
Lerna is a tool for managing JavaScript projects with multiple packages. Sometime, in a large code base system, we need to split the code into the different modules or packages due to code sharing or single responsibility. However, it’s quite hard to mange a big project when develop, testing or even release.
So Lerna focuses on handling the mono-repo management and help you to construct a mono-repo project easily, link the dependency between different modules and release on NPM.
In the next couple of articles, we will learn Lerna by example. Before that let’s understand the running mode of Lerna firstly:
Fixed/Locked mode
This is default mode but not very usual to use. This mode need to maintain a single package version in lerna.json
and this version will be operated on every packages. The most famous case is Babel.
Independent mode
In this mode, each version of packages is separated and allow developer to choose version to release when publishing. To enable this mode, you are supposed to assign version
property as independent
in lerna.json
file or add--independent
argument when running lerna init
command.
When I started to play with Lerna, I realize it’s noisy that you have to publish some fake packages to NPM and have a git repository on GitHub or the other public git host to see what’s going on. Anyway, you can configure your npm packages and git repository as private but just need a few money. So I decide to create an independent environment built by Docker so that you can test Lerna within a private environment.
Please check lerna-tutorial-example.
lerna-tutorial-example gives you three docker containers:
npmserver
: It’s a npm server built by verdacciogitserver
: Git server which already contains a bare repositoryworkspace
: You will clone a dummy project and do all of the Lerna testing here!
Because gitserver
only rely on SSH protocol for git connection, before start setup, please make sure you have a SSH key in your local machine. You can follow below commands to generate it if you don’t have:
$ cd ~
$ mkdir .ssh
$ cd .ssh
$ ssh-keygen -t rsa
It’s time to see how to use Lerna in docker:
$ git clone https://github.com/AllenFang/lerna-tutorial-example.git
Setup SSH
Copy your local SSH key to gitserver
:
$ cd lerna-tutorial-example
$ cp ~/.ssh/id_rsa.pub ./docker/git-server/keys
$ cp ~/.ssh/id_rsa ./docker/git-server/keys
Start Docker
All the docker configs are placed in docker
dir, lerna-tutorial-example use docker compose to construct the different services, so just follow below commands to start docker compose services:
$ cd docker
$ docker-compose up -d
After above commands, npmserver
and gitserver
containers will be started in the background mode. Next, we are going to launch to workspace
container and setup a Lerna project for testing, You can execute below command to launch workspace
everytime:
$ docker-compose run workspace sh
When you launch workspace
, there’re few steps you need to setup in workspace
container:
Setup NPM
$ npm set registry http://npmserver:4873
$ npm adduser --registry http://npmserver:4873 # key in your username, password and email
After finishing above two commands, you can open browser and do login via http://localhost:4873. After login, you will see no any package published yet. So there’re still two steps you need to do as below:
Setup Git
$ git config --global user.email "you@example.com"
$ git config --global user.name "Your Name"
Setup Dummy Project
Still in the workspace
container, you can clone a Lerna project(called: examples) from remote git:
$ git clone ssh://git@gitserver/git-server/repos/examples.git
$ cd examples
$ npm install
examples is a Lerna project with independent mode and have two different NPM modules: module1 and module2.
Lerna Testing
After above three main steps in workspace
container, right now you can try to publish this Lerna project to the NPM by:
$ ./node_modules/.bin/lerna publish
You will see a Lerna prompt for each package that has changed to specify if it’s a patch, minor, major or custom change.
After Lerna packages published, you are supposed to see above result which means module1 and module2 already published to NPM!! Then you can visit http://localhost:4873 to verify again:
In addition, you can find Lerna also help you to add a tag per module via git tag
command.
Conclusion
In this article, we introduce lerna-tutorial-example which allow you to play with Lerna in an independent environments. In the next post, I share some quick tips and common questions about Lerna, feel free to check: 5 tips about lerna