Choosing between "one project per repository" vs "multiple projects per repository" architecture.


In our company, we have modularised most of the projects and are facing one of the biggest design hurdles: one project per repository or multiple projects per repository architecture.

One of the biggest reasons of following one project per repository is being able to release individual components.

What are your thoughts? What do you guys follow?

Start a personal dev blog on your domain for free and grow your readership.

3.4K+ developers have started their personal blogs on Hashnode in the last one month.

Write in Markdown · Publish articles on custom domain · Gain readership on day zero · Automatic GitHub backup and more

Tommy Hodgins's photo

I think the question is: “Are these projects meant to be used together?”

  • if yes: single or multiple repositories is okay
  • if no: multiple repositories only

I have released individual projects as repositories, and also grouped 'families' of plugins together in single repositories as well. My CSSplus project is 6 plugins that work independently of each other, but work in similar ways and can be used together to do some really cool stuff. I worried that if I made 6 individual repositories that people wouldn't realize they could be used together.

Another group repository I've created is the reproCSS plugin, which has 1 main plugin, plus 10 little mixins which are really totally independent JavaScript plugins in their own right, and can be used with or without the main plugin.

Just this last weekend I've released another plugin called respec that could work as a reproCSS plugin, or by itself, but this time I released it in its own repository instead of making it the 11th 'mixin' in the reproCSS repository.

So what's the difference?

I believe people who stumble across any of my CSSplus plugins will discover the other plugins.

I believe the people who stumble across reproCSS or any of the mixins I've included in that repository will be aware of the other plugins there, but probably not know that 'respec' exists or that it can be used with 'reproCSS'.

I also believe people who find 'respec' won't necessarily discover 'reproCSS' or realize that they can use it with that, or be aware of any of the other mixins from that repository.

As far as discoverability is concerned, you can't go wrong from putting more than one project in a repository - but splitting things into their own repositories also gives you more control over documentation, issues, and if you had open-source contributions over pull requests as well.

Arpit Mohan's photo

Monorepos are increasingly becoming more popular. Over the last few years, I've gravitated towards a mono-repo style of organizing code to primarily reduce the amount of overhead required to manage multiple repos. There are some cons to this approach but they are fixable.

Most applications (especially web) function by stitching multiple applications together. This means that whenever there's a bug or a feature request, often, changes need to be made to multiple applications. If you have a multiple repositories, then you need to create multiple issues on your issue tracker to track those changes individually. Alternatively, if a bug is being filed, the reporter needs to know which application to file it against or the tech lead needs to organize the bug and move / re-file the bug against the requisite application. This is a huge pain. Monorepo to the rescue!

The only thing that a Monorepo complicates is the automated build process. This is a much easier problem to solve because it's just code. If you need to release individual components, you can have a build script that inspects commits and looks at the files that have changed. It then initiates a build for only those applications. Or, you can have a nightly build that builds all the applications and releases binaries to S3 or Github or whichever platform you use to distribute deliverables. Hosted build systems such as CircleCI (or even Jenkins) allow you perform these actions out-of-the-box and it's not much more complicated.

As a general principle, while organizing code or workflows, IMHO, it's much better to simplify the process for humans grokking as compared to machine grokking. Hence, I lean towards single branch development, monorepo and the like.

Glauco Leme's photo

The decision relies on the business rules and on singularities of your project.

In my case, working with multiples repositories makes the organization more scalable IMO. With a single big monorepository the deploy and the controlling of the branches was quite crazy. On the first step after migrating to multiple repositories, what I was doing is to develop scripts to prepare the development/testing environments cloning several repositories and updating them.

But there are amazing tools today to help with this task, like meta ( from Matt Walters. It makes the work with multiple repositories quite easier, is a good option to organize the repositories and to prevent new users to make mistakes.

Ron McCranie's photo

We have a front-end repo, back-end repo, and a pattern/style guide repo. They all work together to form the whole site but they are kept separate because they are versioned separate. The workflows are different and the teams are different. Sometimes in an enterprise setting, like ours, you can do multiple repos for one project depending on the team structure, technologies being used, and the security necessary for the application.

Jos Faber's photo

Multiple repo's can almost always be grouped in software (e.g. BitBucket), but multiple projects in one repo cannot easily be "split" anymore.

Furthermore, working on one projects out of a multiple-project-repo requires you to checkout all of the projects. That to me would be a perfectly good reason on it's own to do just one-per-repo.