Design a frontend monorepo

Start with who uses the repo and what they need from it. Then draw the projects and the layer that runs them.

• Functional: share code between apps without publishing it first; change a shared package and update every consumer in the same pull request; build, test and lint each project on its own; publish the few packages other repos use.
• Non-functional: CI time per pull request grows with the size of the change, not the size of the repo; every directory has an owner who reviews changes to it; a release never ships a package against a dependency it wasn't tested with; a new engineer can run one app on day one.
• Scope cuts: how many apps and teams (three and five here), whether anything is published outside the repo (three packages are), and whether it's JavaScript only (it is; a multi-language repo changes the tooling).
• Architecture: apps on top, then feature packages, then UI and data, then utilities, with config every project shares. Under them sit two pieces of tooling: the package manager's workspace (one install, local packages linked) and a task runner (task graph, cache, affected runs). Name the alternatives: a polyrepo, or micro frontends, which is a deploy strategy and works with either repo shape.

Monorepo tooling comes in three layers, and most repos combine one tool from each: a package manager that installs and links, a task runner that orders, caches and filters tasks, and a release tool that bumps versions and writes changelogs.

• Package managers (pnpm, npm, Yarn) give you workspaces. pnpm adds the workspace: protocol, strict node_modules and catalogs for shared versions. None of them caches tasks.
• Task runners (Turborepo, Nx) read the dependency graph, hash each task's inputs, and skip or restore what they've seen before, locally and from a shared cache. Nx also ships boundary rules, generators and its own release command. Turborepo keeps a smaller core and points to Changesets for releases.
• Pick by what you need, not by popularity. Tick your needs in the demo to see which common stacks cover them.

Two ideas make a big monorepo fast. Affected: a change can only break the projects that depend on it, so run only those. Caching: a task with the same inputs gives the same outputs, so hash the inputs and reuse the result when the hash matches.

• The task graph orders the work. A project's build waits for its dependencies' builds (^build); tasks with no path between them run in parallel.
• A task's hash covers its own files, its config, the lockfile entries and env vars it uses, and its dependencies' hashes. On a hit the runner restores the saved outputs and replays the logs instead of running the task.
• Affected is coarse and the cache is precise. Change the ESLint config and every project is affected, but only lint misses the cache. Revert a change and the old hashes hit again.
• A local cache only helps the machine that filled it. A shared (remote) cache lets CI reuse your laptop's builds and lets every pull request reuse main's.

Without rules, a monorepo turns into one big app: anything can import anything, and every change affects everything. Boundaries keep the graph shaped the way you drew it, and ownership tells you who has to agree to a change.

• Layer rules: each kind of project may only import the kinds below it. Tag projects (by type, and often by domain or team) and let a lint rule reject imports that break the rules.
• Public entry points: a package's exports field is its API. A deep import into src/ couples you to files its owners think are private.
• No cycles: two packages that import each other can't be built in any order, and neither can change without the other.
• Ownership: a CODEOWNERS file maps paths to teams (the last matching pattern wins), and branch protection requires one of them to approve. Internal packages can change in lockstep with their consumers; published ones need versions and a changelog because other repos depend on them.

Shared code makes dependency mistakes everyone's problem. Three decisions matter: one version of each library or many, whether a project can use a package it never declared, and how published packages get versioned.

• Workspace linking: internal packages are symlinked, not downloaded ("@acme/ui": "workspace:*"), and the protocol becomes a real version when published.
• Single-version policy (pnpm catalogs, or a lint check) means one copy of each library and one upgrade for everyone, which every project's tests must pass. Independent versions let each team upgrade alone, at the price of drift and duplicate copies.
• Hoisting and phantom dependencies: a flat node_modules lets code import packages it never declared, until someone else removes them. An isolated layout (pnpm's default) links only declared dependencies, so the mistake fails right away.
• Releases: record each change with a bump type, then version everything at once. A dependent whose range the new version leaves gets a patch bump (Changesets; since 3.0 that includes peer dependencies). A fixed group moves in lockstep; independent versions move alone.

"Won't CI get slow?" is the first objection to any monorepo. Running everything does grow with the whole repo. Running only affected projects, skipping cached tasks and spreading the rest over agents makes CI grow with the change instead.

• The four strategies stack. Affected runs depend on git history (fetch enough of it in CI); the shared cache needs complete hashes; parallel agents can't beat the longest chain of dependent tasks except by caching tasks on it.
• Run one app without building the world: start its dev server and let the runner build only its dependencies, or have the app consume packages as source (no build step, nothing to cache, more work for the app's bundler).
• Incremental type checking: TypeScript project references and tsc -b rebuild only stale packages. The cost is composite configs and emitted declaration files.
• Generators scaffold a new package with the right config, tags and owners, so new code starts inside the rules. They do need maintaining. Editor speed drops as the repo grows: project references and scoped workspaces keep the language server on what you have open.

A lot of the pain in a large monorepo goes back to choices made in its first weeks: where code goes, how a package is shaped, and who reviews what. These rules settle them early. Try them on the sample repo in the demo.

• Keep code in two top-level folders: apps/ for what you deploy and packages/ for what you share. The root holds only workspace and tooling files (the root package.json, the workspace file, the task pipeline, CODEOWNERS), so the whole layout fits on one screen.
• Give each package one purpose, its own package.json, and an exports field listing its public entry points. If you need "and" to describe a package, split it. Whatever exports leaves out is private, and its owners can change it without breaking anyone.
• Put every package under one npm scope and name it after its folder, so packages/ui is @acme/ui. Mark internal packages "private": true so nobody publishes them by accident.
• Agree on the layers before the second app arrives. Here that is apps, then features, then UI and data, then utilities, with imports only going down. Tag each project with its layer and check the rule in lint and CI, so it holds even when a reviewer misses it.
• Ship shared config (TypeScript, ESLint, test setup) as packages that projects extend. Pin the package manager in the root package.json and keep third-party versions in one catalog, so laptops and CI install the same tools.
• Give every project one owning team in CODEOWNERS. Write the catch-all first and specific paths after it, because the last matching line wins. Then turn on required code-owner review in branch protection; without it, owners are only requested as reviewers.