Creating, Testing and Building a Monorepo With Lerna and Yarn

I showed you the best practices to create a JavaScript SDK in last article. One of the best practices that I described was the importance of controlling the package’s version and share the codebase between them.

In this article, I’ll show how monorepo can help you to achieve those principles.

What is Monorepo?

In a nutshell, monorepo is a strategy where you will have all the application’s code in the same repository.

There are some cases that a monorepo fits well. For example, when you have an application with a mobile app, backend, frontend, and so on. With monorepo, we will have a folder for each of these parts and share code between them.

Another suitable case for this strategy is when you are creating a lib. The Angular framework is a famous example of that and uses this project structure.

The project has a well-done decoupling with a lean core separated from the other modules as animations, forms, router, etc. In this Angular project in specific, all the modules have the same version number.

But with monorepo, you can have unique versions for each module as well.

After publishing this monorepo to NPM, we will have separate packages for each model.

Three Main Benefits

• ♻️ Ease of code reuse — When we have a project with many modules, but with the same codebase, it is good to have all these modules altogether in a monorepo. For example, an SDK that has a package for different frameworks’ components.
• 📦 Simplified dependency management — In a multiple repository environment where many projects depend on a third-party dependency, that dependency might be downloaded or built many times. In a monorepo, the build can be easily optimized, as referenced dependencies all exist in the same codebase. You can achieve it using Yarn Workspaces.
• 🚀 Unified versioning — We have one source of truth for all packages. It’s a good practice when you have an API with sub-modules, it will allow you to identify whether the module you are using came from the same codebase. For example, when a new version of Angular (core package) is published, all “sub-packages” will have the same version.

Let’s Create Our Monorepo

For our example, I will create an SDK that has support to some frameworks components (React, Vue, and Angular).

Getting Started

First, we will execute the following command lines.

$ mkdir my-sdk && cd $_
$ npx lerna init

npx lerna init will create the Lerna configuration file as well as the package.json file and the packages folder:

.
├── lerna.json
├── package.json
└── packages

We’ll modify the lerna.json and package.json files to support Yarn Workspaces (available since [email protected]+).

For the lerna.json file will add the following properties:

• "npmClient: "yarn" : to run all commands with yarn
• "useWorkspaces": true : to enable integration with workspaces

For the package.json file will add the following property:

• "workspaces": ["packages/*"] : where the modules/packages are located

Creating the Packages

Now it’s time to create our packages that will be orchestrated by Lerna and Yarn. In this example, we will create four packages: core, react, vue, and angular.

$ mkdir -p packages/{core,react,vue,angular}

Now we have this structure:

.
├── lerna.json
├── package.json
└── packages
    ├── angular
    ├── core
    ├── react
    └── vue

The core folder will contain our shared code between our packages. We can have our server integrations, interface definitions, base classes, and utilities for building the SDK components.

The other folders will have our components’ particular behavior. Each package will have the package.json file with its dependencies.

For instance, you can follow these articles to create the component for each framework in this example.

• https://angular.io/guide/creating-libraries
• https://github.com/transitive-bullshit/create-react-library
• https://vuejs.org/v2/cookbook/packaging-sfc-for-npm.html

Pro tip: remove all node_modules folders inside the packages and then run yarn install in the root folder. It will install the dependencies for all packages. We will only have a node_modules folder inside a package, whether we have a version conflict between the packages dependencies.

Testing and Building All Packages

Now that we have all packages created, we can build our whole repo. We will use Lerna to execute the scripts inside our packages.

First, we need to create a build script inside each `package.json`. For example, if you followed the instructions to create a React lib above the build and test script inside the packages/react/package.json must be:

{

  "name": "my-sdk-component",
  "version": "1.0.0",
  ...
  "scripts": {
    "build": "microbundle-crl --no-compress --format modern,cjs",
    "test": "run-s test:unit test:lint test:build",
    ...
  },
  ...
}

To run all the packages tests and build them, we will define theses scripts in our root package.json.

Now to test and build your entire repo just run:

$ yarn test
$ yarn build

Conclusion

Now we know how to create, test, and build our monorepo. In the next article, I’ll show you how to publish those packages using the GitHub Actions CI/CD.