Testing a project contained in a monorepo

A ‘monorepo’ is the term used to describe the organization of multiple distinct projects with well-defined relationships into a single code repository¹ rather than having each project be in its own dedicated repository.

Monorepos have been around for a while, but if you haven’t worked with them before, figuring out how to test changes made in one of the projects contained within a monorepo in a local or deployed staging environment might not be the most intuitive.

For this guide, we’re going to assume that we’re dealing with Node projects and packages.

Local environment

To test a project that lives within a monorepo in your local environment:

• Run npm link within the directory of the monorepo project that you want to test
• Run npm link within a project that has the monorepo project listed as a dependency that you will be using to test the changes made in the monorepo project
• Run the test project

If you’re interested in learning more about how npm link works under the hood that leads to this working, there’s a really great Medium article by Alexis Hevia that can be read here.

Staging environment

If you’re looking to test your changes in a deployed environment instead, you’ll have to do something a little bit different.

When projects are in their own dedicated repository, it’s usually possible to push the changes to a git branch and then reference that branch as the version of the project in the package.json file such as <your organization or user>/<project repository>#<branch> (rather than ^1.2.3).

Due to expectations on the structure of the backing repository needing to match a modules' published structure which doesn’t exist in a monorepo project², we instead will create a tarball of the modified project and store the tarball on a predictable path to be referenced as the version of the project in the package.json file.

To do this:

• Run npm pack within the directory of the monorepo project that you want to test
• Commit the tarball to a git branch that you’re using for testing purposes
• Push the branch to github
• Update the version of the monorepo project to reference the tarball file - "https://github.com/<username>/<repo>/raw/<branch>/[path]/<tarball>" - within the project that has the monorepo project listed as a dependency that’s being used to help test the changes
• Deploy the test project

Credit for the above workaround goes to Stephen Peck and the gist he made.

Conclusion

While requiring a little bit of work, testing a project contained within a monorepo is not too bad once you’re made aware of the setup needed to allow npm to install the modified project correctly.

Hopefully this was helpful, happy testing!