January 12, 2023
Just use a monorepo

A before-and-after of my setup.

I wrote last month about having migrated Buttondown from a number of separate microrepositories to a single monorepo. I've since completed the migration, and the slight irritation I felt from having to unwind a bunch of technical choices with deployment + continuous integration has faded.

I am here to tell you: if you are running a software business and you aren't at, like, Google-tier scale, just throw it all in a monorepo. I am kicking myself for not having done this to begin with.

Here is a list of I think reasonable drawbacks of having a monorepo if you are not a Google-tier company:

  1. You cannot apply role-based access controls to certain parts of the repository for security/compliance reasons.
  2. You cannot open-source certain parts of your repository. (This was the biggest sticking point for me for a while — I want, ideally, everything in Buttondown to be open-source except the core plumbing and author-facing application.)

Conversely, here are a list of things that became an order of magnitude easier now that my entire codebase is in a single repository:

  1. Rolling out API changes concomitantly with downstream changes to the documentation or the OpenAPI spec.
  2. Introducing feature-level changes and the blog post announcing those changes.
  3. Context-switching between different workspaces with subtly different configurations.

You may be reading this short essay and thinking: "Yeah, no shit! Of course you do not need a monorepo when you're talking about, like, 150K lines of code." Congratulations — you are sensible, and well adjusted, and certainly wiser than I was six months ago.

But I know there's a few of you out there who are clinging to something — some irrational reason why you have your welterweight project split across four separate repositories.

Maybe it's some abstract sense of purity; maybe it's because you didn't realize most IaaS let you deploy from a subfolder. Whatever the reason is: trust me. Move it into a monorepo. If you do and you end up regretting it, [email me] and I'll donate to the charity of your choice.

To wrap up, I will deputize two people who are smarter than I am who have also opined on the subject:

  1. Dan Luu
  2. Gregory Szorc
Sign up for the greatest newsletter in the world.
Email not your thing? Well, that's a whammy. Twitter or RSS, I guess?
Buttondown is the easiest way to start a newsletter.
Get started today: