Monorepo mechanics: pnpm workspaces, the Turborepo task graph, and packages that earn their boundary

pnpm workspaces: links, not copies

Before you add Turborepo, the question is what gives you actual boundary enforcement rather than just folder organization. The answer is the package manager substrate.

The substrate is pnpm-workspace.yaml declaring apps/* and packages/*. Each package keeps a real package.json, and internal dependencies use the workspace protocol — "@acme/ui": "workspace:*" — which pnpm resolves to a symlink into the local package, never the registry. Two properties make this the boundary substrate rather than a convenience. First, every package declares its dependencies explicitly: the package.json is the boundary contract, machine-checked on install. Second, pnpm’s strict, non-flat node_modules means a package can only resolve what it declared — the classic phantom dependency (importing a package that some hoisted neighbor happened to install) fails fast instead of working in dev and detonating in a different install order later. A monorepo on a hoisting package manager has folders; a monorepo on pnpm has enforceable edges.

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

// apps/web/package.json — the edge is declared, not implied
{
  "name": "web",
  "dependencies": {
    "@acme/ui": "workspace:*",
    "@acme/billing": "workspace:*",
    "next": "15.1.0"
  }
}

The task graph is the cache graph

Turborepo reads turbo.json and builds a directed graph of tasks: "build": { "dependsOn": ["^build"] } means “my build needs my dependencies’ builds first” — topological order falls out. The leverage is in what happens before a task runs: Turborepo computes a content hash over the task’s inputs — the package’s source files, the hashes of its dependencies’ outputs, the declared environment variables, the relevant lockfile slice, and the task configuration itself. Hash seen before: skip the work and replay the cached outputs and the captured logs, byte for byte. Hash new: run and cache. Because a dependency’s output hash is an input to every dependent’s hash, invalidation travels exactly along the dependency arrows — and nowhere else.

The honest numbers from the repo in the hook: a cold full build (nine packages, two Next.js apps) runs 20–35 minutes in CI. With a remote cache, the hash-keyed artifacts live in shared storage: CI builds once, every other runner — and every laptop — replays. Warm median PR: 4–7 minutes, because only the changed subgraph executes; a PR touching nothing buildable replays everything in under a minute. Add --filter=...[origin/main] and CI does not even consider tasks outside the affected subgraph. None of this requires the cache to be clever. It requires the graph to be cuttable — which is a property of your package boundaries, not of Turborepo.

Extracting packages: ui, config, domain

What earns extraction out of an app: code consumed by two or more apps, testable in isolation, owning its own dependencies. Three archetypes cover most repos. packages/ui — the design system — has a real decision attached: ship it as source (the package exports raw .tsx, and each Next.js app lists it in transpilePackages so the app’s compiler processes it like its own code) or prebuilt (the package gets a tsup/rollup build task emitting dist/). Source-shipped wins on iteration speed: zero bundler config in the package, and editing a button hot-reloads in every running app instantly. Its cost is symmetrical: every consuming app recompiles the package on every build, and that compilation is cached as part of the app build, never as its own task. Prebuilt inverts the trade — the package build is cached and shared, app builds are faster, publishing externally becomes possible — at the price of bundler config, watch-mode orchestration, and the “works in app A, stale dist in app B” class of bug. Default to source plus transpilePackages; switch when app build time or external publishing forces you.

// apps/web/next.config.js
module.exports = {
  transpilePackages: ['@acme/ui'], // compile source-shipped internal packages
};

packages/config holds eslint-config and tsconfig bases that every package extends — one upgrade PR moves the whole repo, drift becomes structurally impossible. packages/billing-style domain packages are the highest-value extraction: pure TypeScript, no React, so typechecking and testing business rules no longer requires building an app at all.

Versioning honestly

Internal packages need no versions. workspace:* means every commit is the version: consumers always compile against HEAD, there is nothing to publish, nothing to bump, no semver to argue about in review. Changesets earn their ceremony in exactly one case — when a package is published outside the repo (npm or a private registry) for consumers who are not in the workspace. Adopting changesets for internal-only packages produces version-bump PRs that no human and no machine consumes: pure process theater. The honest rule: workspace:* until the day an external consumer exists, changesets from that day for the published packages only.

The payoff, and the god package that erases it

The boundary payoff compounds in CI: turbo run typecheck test --filter=...[origin/main] means a PR touching packages/billing runs billing’s checks plus the two apps that import it — the docs app and five other packages replay from cache. Typecheck time stops scaling with repo size and starts scaling with blast radius.

The failure mode is the one from the hook, and it deserves its mechanism spelled out: packages/shared — utils, helpers, “common” — imported by every package. Its position in the graph means its hash feeds every other hash; its grab-bag nature means it changes constantly (70 percent of PRs in the incident repo). Multiply: near-zero cache hits, full-graph rebuilds on every change, and a team concluding “the monorepo made CI slower” when the graph topology did. Detection is mechanical — render the package graph (turbo can; dependency-cruiser for finer grain) and track cache hit rate per PR as a first-class CI metric. The fix is splitting by domain and change frequency: stable leaves (@acme/result, @acme/dates) separated from hot domain logic, so a billing change re-hashes billing’s dependents and nothing else. The cultural fix matters more: never let a package be named shared or utils again — names that cannot say no to a new export.