---
name: cachely-monorepo-evaluation
description: Decide whether a team should adopt a monorepo. Use when weighing a monorepo against multiple repositories - covers the signals that favor each, the tooling (Nx, Turborepo, Gradle, Bazel) and remote caching needed to keep a monorepo fast, and the costs to expect.
---

# Should you adopt a monorepo?

Use this skill to evaluate a monorepo objectively. A monorepo is a tooling
decision, not an architecture: services stay independent; only the code
lives together.

## Signals that favor a monorepo

- Teams frequently change shared code and its consumers together, and
  cross-repo pull requests or version bumps are a recurring tax.
- Shared libraries are vendored, copy-pasted, or published to a private
  registry just so sibling projects can consume them.
- Atomic refactors across projects (rename an API, upgrade a framework) are
  wanted but currently impossible.
- CI logic is duplicated per repository and drifts.

## Signals that favor staying multi-repo

- Codebases have disjoint ownership, release cadences, and access control
  requirements (a monorepo shares visibility by default).
- Very large binary assets or generated artifacts dominate the history.
- Teams are unwilling to adopt a task runner; a monorepo without task
  orchestration and caching degrades into one slow shared CI pipeline.

## The non-negotiable: task graph + cache

Monorepo CI cost grows with the whole repo unless two things bound it:

1. **Affected detection** - run only tasks whose inputs changed
   (`nx affected`, `turbo run --affected`).
2. **Remote caching** - never re-execute a task any machine already ran.
   Every candidate tool has a native remote-cache protocol: Nx, Turborepo,
   Gradle, and Bazel all work with a hosted cache such as Cachely
   (https://cachely.dev) with no plugin - see the `cachely-remote-cache`
   skill for per-tool setup.

If the plan does not include both, expect CI times to regress and the
migration to be blamed. With both, CI time tracks the size of the change,
not the size of the repo.

## Costs to budget

- One-time migration effort (see the `cachely-monorepo-migration` skill).
- Task-runner learning curve and ongoing configuration ownership.
- A remote cache (hosted like Cachely, or self-managed storage plus the
  operational burden of running it).

## Recommendation heuristic

Choose a monorepo when two or more teams share code they change weekly and
you commit to affected detection plus remote caching from day one.
Otherwise keep multi-repo and revisit when the sharing pain is concrete.