A monorepo is a repository strategy, not simply several applications placed in one folder. The value appears when related products can make coordinated changes, share well-defined libraries, and prove which tests or builds are affected. The cost appears when every package can reach every other package, a shared utility becomes an accidental platform, or a small edit triggers an opaque full rebuild. A useful monorepo structure makes ownership, dependency direction, build scope, and release responsibility visible before those costs are paid in production.
Choose the structure from the work that needs coordination. A product with a web app, Node service, design system, and shared domain types may benefit from atomic changes, while an unrelated collection of products may be better served by separate repositories and published packages. The surrounding system matters too: TypeScript architecture, internal tool UX, Node.js APIs in production, and event-driven systems in production each create package and ownership boundaries that should inform the repository.
Define the purpose before the folder tree
Write the outcome the repository must improve: coordinated API changes, safer shared components, repeatable local setup, faster affected builds, or a consistent release path. Then list the products, libraries, teams, and deployment units that participate. Do not use monorepo as a synonym for a single deployment or a single team. Nx’s monorepo guidance distinguishes code collocation from the tooling and boundaries that make a monorepo useful. If the team cannot name the coordination problem, it is too early to decide that a monorepo is the answer.
| Question | Decision to record | Evidence |
|---|---|---|
| Coordination | Which changes must land atomically? | Representative cross-project change. |
| Ownership | Who approves each package and contract? | Owner file and review route. |
| Sharing | Which APIs are public within the repository? | Package export and consumer test. |
| Build | Which targets should be rebuilt or tested? | Affected graph and timing baseline. |
| Release | Which units version and deploy together? | Release manifest and rollback path. |
Set package boundaries that can be enforced
A package boundary should say what a consumer may import, which data or runtime assumptions apply, and who can change the contract. Keep application code from reaching another application’s private internals. Put shared validation, types, or UI components behind explicit packages with documented exports. Use visibility rules or lint checks where the tool supports them. Bazel’s dependency guidance shows why direct dependencies, limited visibility, and appropriate granularity matter: implicit transitive use creates a hidden contract that later refactoring cannot safely remove. The same principle applies in a JavaScript workspace even when the enforcement mechanism is different.
Make the dependency graph the operating model
Draw the graph from actual package relationships, then compare it with the declared graph. A shared package that imports a product-specific module is usually a boundary failure, not an acceptable shortcut. Use project references, workspace metadata, or build-tool configuration to make order and affected scope explicit. TypeScript Project References can turn a large TypeScript tree into separately checked projects with clearer build relationships. Keep a small number of architectural rules that fail loudly: domain packages cannot import delivery packages, libraries cannot reach deployment configuration, and apps consume public exports rather than source paths.
- One clear purpose and owner for each package.
- An explicit public entry point rather than unrestricted source imports.
- A dependency direction that can be checked in CI.
- Examples or contract tests for behavior consumers rely on.
- A change policy for breaking exports and generated artifacts.
- A route for deprecating a package instead of leaving abandoned code reachable.
Choose tooling by the evidence it exposes
Package managers, task runners, and build systems solve different parts of the problem. pnpm’s workspace manifest guidance documents how a workspace declares package discovery and linking, while a task graph tool can calculate dependencies, cache results, and run affected work. Turborepo’s repository guidance is a useful reference for workspace layout, but no tool decides whether a package boundary reflects a sound product boundary. Select tooling that gives the team a reproducible local command, a visible dependency graph, stable cache keys, and an escape hatch when a result is wrong. Avoid adopting several overlapping task conventions before the workflow is understood.
Design selective builds without hiding correctness
A fast affected build is valuable only if the affected graph is sound. Establish a baseline for a clean build, a package-only change, a shared-library change, and a generated-file change. Check that cache hits are reproducible across machines and that a cache miss does not change the result. Run a periodic full validation to catch undeclared relationships. Separate checks that prove a package from checks that prove an integrated product. The CI record should show what ran, why it ran, what was reused, and who owns an unexpected expansion in scope.
Align code ownership with release responsibility
Repository access is not the same as permission to change every package. Assign maintainers for shared contracts, require domain review for sensitive boundaries, and keep an escalation path when an owner is unavailable. Decide whether packages use independent versioning, coordinated releases, or a hybrid model. A web client and API may need an atomic change, while a stable utility can release separately. Document the version and deployment relationship so a reviewer can tell whether a pull request changes one product or several. The TypeScript architecture guide is a useful companion when the package graph begins to mirror application layers.
Migrate in evidence-bearing slices
Do not begin by moving every repository and rewriting every import. Inventory current build commands, deployment units, ownership gaps, duplicated dependencies, and cross-repository changes. Choose one product slice that has a meaningful shared dependency and a measurable pain point. Preserve its release path while the repository shape changes, then compare build time, failure diagnosis, review routing, and change lead time with the old baseline. Each slice should leave behind a boundary rule, a rollback option, and a reason to continue. If the evidence does not improve coordination or safety, stop expanding the structure.
| Risk condition | Control | Signal to review |
|---|---|---|
| Private code becomes shared | Restrict exports and check import paths. | New cross-domain dependency count. |
| Every edit runs everything | Use an explicit task graph and affected calculation. | CI duration by change type. |
| Cache hides a bad graph | Run periodic clean and full builds. | Cache correctness and unexpected misses. |
| Shared package lacks owner | Require named maintainer and review route. | Age of unowned change requests. |
| Release coupling surprises teams | Publish compatibility and deployment rules. | Rollback or coordination incidents. |
Review the structure as a living product
Review the monorepo when the number of teams, deployment units, or shared packages changes, not only when CI becomes slow. Ask whether ownership remains clear, whether the public package surface is growing intentionally, whether private imports are appearing, and whether a package can be tested without a full product environment. Keep a small scorecard with build reliability, affected-test precision, review wait time, dependency churn, and cross-team incident patterns. Those measurements support a decision to split, consolidate, or add an enforcement rule instead of turning repository fashion into policy.
Write the working agreement teams will use
A repository decision becomes useful only when it changes everyday behavior. Write a short agreement that explains where a new package belongs, how a dependency is approved, which checks a change must run, and who is called when a shared path breaks. Include examples of a normal application change, a public contract change, a security-sensitive change, and a migration that spans deployable units. The agreement should also state what a team may do without central approval. Clear autonomy is part of the control: when people know the local path, they are less likely to create private forks or bypass the graph.
Review the agreement alongside the repository after the first two or three releases. If developers routinely ask where code belongs, a boundary is missing. If owners are approving changes outside their context, the routing is too broad. If the fastest way to recover is to copy a package into an application, the release contract is incomplete. Capture these observations as design evidence and choose one small correction. The agreement should become shorter and more specific over time, because the repository is teaching the organization how to make safe changes.
Monorepo structure takeaways
- Choose a monorepo to coordinate a real set of changes, not to follow a tooling trend.
- Make package purpose, public exports, dependency direction, and ownership enforceable.
- Use task graphs and caches only when their correctness can be checked.
- Keep build, version, and deployment relationships visible to reviewers and operators.
- Migrate one product slice at a time and compare evidence with the previous workflow.
- Treat splitting or stopping as valid outcomes when the structure no longer improves the work.
Monorepo structure FAQ
How large should a monorepo be?
Size alone is not a useful threshold. A small set of closely coordinated applications may benefit early, while a larger set of unrelated products may not. Use the number and frequency of atomic changes, shared contracts, ownership clarity, and build evidence to decide.
Do workspaces solve monorepo architecture?
Workspaces solve package discovery and linking, not domain boundaries, review ownership, release coupling, or dependency hygiene. Pair package-manager features with explicit exports, graph checks, and an operating agreement.
Should every team use remote build caching?
Only after local builds are reproducible and cache keys reflect all relevant inputs. Remote caching can reduce repeated work, but it can also hide an incomplete graph if teams never run a clean validation.
Conclusion: make the repository accountable
A healthy monorepo structure gives teams coordinated change without erasing product ownership. Define the reason for sharing, set boundaries that tooling can inspect, expose the affected work, and connect package ownership to release responsibility. Then let measured build, review, and incident evidence decide whether the structure should grow, tighten, or split.