Okay, this is going to sound dumb, but I spent two weeks last year arguing with a co-founder about whether to move four small services into a single repo. I lost. We moved them in. Six months later, we moved them back out. Neither of us has ever fully recovered.<\/p>\n
If you’ve been on the internet for more than fifteen minutes, you’ve seen the monorepo vs polyrepo fight. It’s one of those debates where everyone is a little bit right and also extremely certain about it. I used to be certain too. Now I’m less certain and more opinionated, which I think is generally a good trade.<\/p>\n
I’ve shipped both. I’ve shipped a two-service Laravel plus Next.js project that should have been one repo and was three. I’ve shipped a monorepo with six apps and a shared UI package that was great until CI started taking twenty minutes. So here’s what I actually think, with fewer slogans and more scars.<\/p>\n
A monorepo is a single version-controlled repository that contains multiple projects. Not a giant A polyrepo (sometimes “multi-repo”) is the opposite. Each of those folders lives in its own repo, with its own CI, its own releases, and its own So the real question isn’t one repo or many. The real question is what lives next to what, and how do changes ripple through your system when you touch one piece.<\/p>\n The Google engineering paper on their giant monorepo<\/a> is the famous example. Dan Luu wrote a solid summary of the tradeoffs<\/a> back when I was still in university. The short version of the pro-monorepo argument is:<\/p>\n That is all real. I’ve felt all of it. When I moved my React shadcn components into But the part people skip is the cost. In a real monorepo you pay for:<\/p>\n If your team is four people and your CI times are under five minutes, none of this hurts yet. If your team is forty and you’re waiting on The strongest rebuttal I’ve read is Matt Klein’s Monorepos: Please don’t<\/a>. He was at Lyft when they made the opposite decision from Google. His argument, roughly, is that small teams copying Google’s tooling without Google’s tooling investment is a trap. I’ve watched teams adopt Nx because they read a blog post, then spend weeks fighting cache keys instead of shipping features.<\/p>\n Polyrepo wins on a few specific things:<\/p>\n The price is coordination. If your frontend depends on a typed API client, and that client lives in the backend repo, and you also want to version it properly, you now have a publishing step. Congratulations, you are running a miniature npm registry.<\/p>\n Most teams I see default to polyrepo, get tired of the coordination tax, then overcorrect into a monorepo and discover the CI tax is worse. Both taxes are real. You pick which one you’d rather pay, and then you pay it.<\/p>\n I used to think this was a structural question. It’s not. It’s a people question. Here’s what I ask first, roughly in order:<\/p>\napp\/<\/code> folder with everything jammed together. Usually it looks something like:<\/p>\nmy-repo\/\n apps\/\n web\/ # Next.js\n admin\/ # Next.js\n api\/ # Laravel or Go\n packages\/\n ui\/ # shared React components\n config\/ # eslint, tsconfig, tailwind preset\n sdk\/ # typed API client\n turbo.json\n package.json\n<\/code><\/pre>\nREADME.md<\/code> that nobody reads.<\/p>\nthe case for a monorepo that’s honest about costs<\/h2>\n
\n
sdk\/<\/code>, you fix every call site in one commit. No coordinated merges across four repos.<\/li>\npnpm-workspace<\/code> or Go workspaces or Cargo workspaces give you one lockfile, one toolchain version, one source of truth about which library is pinned.<\/li>\npackages\/ui<\/code> and suddenly both apps used the same <Button><\/code>, I almost cried.<\/p>\n\n
apps\/admin<\/code> broke nothing.<\/li>\ntsc<\/code>. You end up adding Turborepo<\/a> or Nx or Bazel, and now you’re also maintaining that thing too.<\/li>\npnpm install<\/code> for three minutes on every PR, it hurts a lot.<\/p>\nthe case for polyrepo, and why I’m not a purist about it<\/h2>\n
\n
the boring framework I actually use now<\/h2>\n
\n