Skip to content

Testing a project contained in a monorepo

Erica Pisani
Erica Pisani
2 min read

A ‘monorepo’ is the term used to describe the organization of multiple distinct projects with well-defined relationships into a single code repository1 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 project2, 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!


📫
Enjoy this post? Subscribe to be notified when I publish new content!
testingtips-and-tricks

Comments


Related Posts

Members Public

How to install a Nerd Font on Warp

I started using Vim as my IDE of choice recently, and one of the things I wanted early on was a more visually appealing icon and font set. I kept reading about Nerd Fonts so I decided to try installing one, but the instructions for doing so were both clear

Members Public

How to change the version of an npm package associated with a specific tag

If publishing experimental npm packages is a somewhat regular part of your development workflow, you've likely experienced some nerves around publishing that package incorrectly such that it becomes the version that anyone newly installing or upgrading the package gets. If you find that you accidentally did exactly this

How to change the version of an npm package associated with a specific tag
Members Public

How to search and filter issues and pull requests in Github by author

If you ever find yourself needing to find issues or pull requests created by someone (or a few someones) in Github, here are a few quick tips for how to do that. First up - when you're looking for an individual, you'll want to use the

How to search and filter issues and pull requests in Github by author