Decision record // Repository
Monorepo or separate repos?
You have a web app, and soon a worker, or a dashboard, or a marketing site. The question arrives the moment there are two deployable things and they share something.
The call
One repo, almost certainly. But note that “one repo” and “a package graph with a build orchestrator” are two different decisions, and most people asking the first do not yet need the second.
When each one is right
One repo
- More than one deployable shares a type, a schema or a client. A web app and a worker that both understand the same rows.
- You want one pull request to change an API and its consumer together, so the two cannot disagree.
- The team is small enough that everybody touches everything.
Separate repos
- Genuinely independent lifecycles, with separate teams shipping on their own schedules.
- Different languages with no shared contract between them.
- A component you intend to open-source and version on its own.
What it costs you later
The cost people quote is tooling, and it is real: task graphs, CI caching, a build orchestrator to configure. The cost people forget is version skew, which is precisely what separate repos hand you instead. A client and an API that disagree about the shape of a response is an entire category of bug that one shared type deletes outright. The mistake in the opposite direction is just as expensive: six packages and a full monorepo toolchain on day one, for a product with a single deployable and one developer. Start with one repository and disciplined internal folders. Add the package graph when something is genuinely shared and the boundary has stopped moving.
Decisions like this one, on your product
This page is a general answer. Yours has constraints I don't know about. The Founding Engineer is 8 weeks with 5 founders where we make these calls on your actual codebase, and your code gets reviewed every week.
New decision records as I write them
One question, one answer, no hedging. Leave your email and I'll send the new ones. No schedule promises, unsubscribe anytime.