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!