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.
To test a project that lives within a monorepo in your local environment:
npm linkwithin the directory of the monorepo project that you want to test
npm linkwithin 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.
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
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
To do this:
npm packwithin 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.
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!