Building a TypeScript Mono-Repository

Published: Dec. 26, 2024

In a recent role, I was asked to build a centralized repository for storing common TypeScript constants, functions, and type definitions to be shared across the company's other TypeScript repositories with the goal of reducing code duplication. Initially this seemed simple enough, I started a simple TypeScript repository which was then built into a single npm package and used in a number of frontend React repositories. Sometime later, we wanted to use this package in a server-side repo. However, this broke the server at runtime by relying on browser only functionality and also installed frontend packages like React in a backend application. To fix these issues, I broke up the centralized repository and converted it into a mono-repository containing multiple packages.

But what exactly is a mono-repository and why would someone find one useful? A mono-repository is a single repository which contains the code for multiple packages or projects. The main benefits of the mono-repository approach are: creating a standardized development environment (ie. dependencies, linting rules and testing standards), avoiding the need to write multiple CI/CD pipelines, and simplifying the development process when changing multiple packages at the same time. However, the main drawback of a mono-repository is added complexity in managing, versioning, and releasing multiple packages.

This is where Lerna comes in. Lerna is essentially the operating system of the TypeScript mono-repository. It provides tools which allow engineers to easily manage multiple packages at the same time. In the following sections I will break down the key aspects of Lerna which I leveraged in the creation and management of our mono-repository.

When creating a new Lerna mono-repository there are two main configuration choices which will need to be made. Do you wish to use npm or yarn to install and manage dependencies, and how do you want to manage the versioning of packages? By default, Lerna uses npm workspaces to install dependencies, however yarn workspaces or pnmp can also be configured. Workspaces reduce duplicate downloads in mono-repositories and create a standardized development environment within the mono-repo by installing the dependencies of all packages into the same node_modules/ directory. For versioning Lerna provides two approaches, fixed and independent. With the fixed approach all packages have the same version, which is useful for versioning a suite of compatible packages tested against each other. The independent approach allows for each package to be versioned independently and only released when changed. In our mono-repository, I chose to use yarn workspaces and independent versioning, but depending on each company's unique needs alternatives can be chosen.

Once properly configured any npm/yarn commands run at the repo's top-level will be run inside each of the packages by Lerna. This makes it easy to lint, test and build all packages simultaneously. When you want to run a command in only a single package you can provide the --scope= flag, or cd to that specific package before running the command.

Lerna also automatically builds a dependency tree of all packages in the mono-repository and creates symlinks between them as necessary. For example, if your React component library package depends on your interfaces package Lerna will build and link the interfaces package before building or running the component library package. This reduces the burden of developing multiple packages, making it easy to guarantee the latest versions of your packages will work together.

The package dependency tree is a recent addition to Lerna which was added by the NX team after they took over management of the Learn repository. Another feature the NX team has added is the Lerna cache. This cache stores the results of npm/yarn commands for each package, and when possible, it will use the cached command output if the package's source hasn't changed.

Lerna also provides several commands for the versioning and publishing of the repo's packages to both public and private npm repositories. The changed command will look at the git history and determine which packages have changed since their last release. This is made possible by tagging the latest commit during releases with the new package versions being released. The changed command then searches the commits since the latest tag for each package and analyzes the files changed. There is also the version command which will allow for the versioning of these changed packages. If independent versioning was selected, this command will prompt for the desired new version of each changed package. Otherwise, it will prompt for a single version to be applied to all packages. Finally, there is also the publish command which can be used to publish the new packages to the npm repo of your choice.

In the end, my simple common repository grew into a mono-repository powered by Lerna which contained 11 packages for everything from React components, to authentication logic, to database clients. All of which shared the same linting and testing quality standards, had documentation auto-generated and deployed, and were published to a private npm repository by a CI/CD pipeline.

Ultimately the choice is yours, and depending on your needs a mono-repository may not be right for your company. However, it is my opinion that any growing company which plans to rely on TypeScript for a significant portion of their frontend and backend projects should create a centralized mono-repository. If not for any of the reasons I've described, then to simply create an environment to define TypeScript code expectations and standards to be used throughout the company.