What are the pros and cons of using a monorepo? What approach did TruStory take?


Monorepos have gained popularity in large organizations such as Google and Facebook as of late. The concept at first seems to go against the computer science ethos of breaking things into small modular pieces.

Large centralized organizations often have dozens, maybe hundreds, of microservices and components that talk to each other. Many of these share dependencies, test infastructure, and are often written in the same programming language. The same engineers may even work across these microservices. In this case, version controlling all these services in a monorepo is a good idea and can often simply things like testing and CI. All the parts can be tested together, so it’s easier to make sure the contracts between them don’t break. Furthermore, all developers are kept in the loop when updating and merging code. The advantages here outweigh the drawbacks of having a large sized repo that’s constantly changing.

Monorepos make less sense in smaller organizations that may have an architecture based on a few components, especially if these are composed of different languages and frameworks, and don’t share too many dependencies. Each repo can be tested and developed in isolation, without being unecessarily polluted with code and checkins from repos that don’t share much in common. Monorepos also don’t make sense in organizations that open source a lot of code. It’s easier for the consumer of a service to only pull in the necessary library or framework, without anything extraneous.

A good hybrid approach that provides advantages of both is to manage issues for all repos in a central organizationl-level project management tool, like Github Projects. This way, all developres are kept informed of changes to all repos. Pull requests can reference issues across all repos and notify all developers.

Ultimately, deciding between multiple repos and monorepos is, like all things in a technology, is a matter of tradeoffs depending on the needs of your organization. Moving to a monorepo architecture is easier than breaking up a monorepo into individual ones, so I would always start with individual repos and migrate to a monorepo if the need occurs. Facebook and Google didn’t start with them afterall.

TruStory decided to use multiple repos for now, since we plan on open sourcing parts of our codebase in the future.


In the projects I’ve worked, the single most important reason for a monorepo is to allow easily running the full app (including any services the app needs in production) on our local machines.

Once a singular product/application is split into separate repositories, I’ve noticed this complicate things in the following ways:

  • Increased setup overhead, now rather than a single repository, you will need to clone, build and run multiple

  • Code changes which span multiple parts of the app will require pull requests in each repository

  • Each subcomponent which has been split out of the monolith will often require a versioning scheme, and this means lots of version bumping that was never required with the monorepo


@iaculch This totally makes sense for a traditional client-server app, where you have full ownership and control of infrastructure. In the decentralized blockchain world, once you deploy your app to mainnet, you no longer have control of infrastructure (miners, validators, etc.). Often, the blockchain part like smart contracts are open sourced, and anyone can run your app on Ethereum, or in the case of TruStory, a Cosmos node. It doesn’t make sense to keep the mobile app and blockchain in a monorepo as they are built, run, and deployed differently, and written in different languages. Ethereum projects often have separate repos for the backend (contracts/chain), and API/clients. For example, check out the repo for Augur.