Monorepo-Abhängigkeiten abstimmen

Monorepo Dependency Alignment

When to Use

Use when upgrading dependencies in a repository containing multiple packages, apps, or services (packages/*, apps/*, crates/*, services/*) managed via workspaces.

The Skew Hazard in Monorepos

In a monorepo, upgrading a library in packages/ui while leaving packages/app or root package.json on an older version creates version skew:

• Dual instances of singletons (react, vue, rxjs, graphql, zod, @opentelemetry/api, pinia) get bundled or loaded into memory simultaneously, causing instanceof failures, broken React hooks (Invalid hook call), or TypeScript type incompatibility (Type 'X' from node_modules/a/node_modules/pkg is not assignable to type 'X' from node_modules/pkg).
• Build caches (Turborepo, Nx) and TypeScript project references (tsc -b) break when workspace packages compile against mismatched @types/* or compiler versions.

Alignment Rules & Practices

1. Single-Version Policy for Shared Infrastructure & Peer Families

Keep shared toolchain and runtime foundation packages on a single unified version across the root manifest and every workspace package:

• Compilers & Typecheckers: typescript, @types/node, vue-tsc, swc, esbuild, vite, rollup, webpack.
• Test & Lint Tooling: vitest, jest, playwright, eslint, prettier, biome.
• Framework & State Singletons: react, react-dom, vue, @angular/*, rxjs, graphql, zod, prisma / @prisma/client.

2. Use Workspace Catalogs & Workspace Protocols Properly

• pnpm Catalogs (pnpm-workspace.yaml): If the repo defines catalog: or catalogs: in pnpm-workspace.yaml (with "catalog:" references in package.json), update the version in pnpm-workspace.yaml so all consuming workspace packages move in lockstep.
• Cargo Workspace Dependencies ([workspace.dependencies]): When root Cargo.toml defines [workspace.dependencies] and member crates use dep.workspace = true, update the root [workspace.dependencies] entry rather than overriding versions in individual member crates.
• uv / Poetry / Composer Monorepos: Check root pyproject.toml [tool.uv.workspace] or Composer path repositories ("type": "path").
• Internal Cross-Package Links: Preserve workspace:*, workspace:^, or workspace:~ protocols between internal packages so local workspace packages resolve to the local source tree rather than fetching a stale published version from npm/Packagist/crates.io.

3. Topological Build Order & TypeScript Project References (tsc -b)

After upgrading any dependency in a monorepo:

1. Clean Stale Build Artifacts: Stale .tsbuildinfo, dist/, or .turbo cache entries can hide type errors in downstream workspace packages that re-export types from an upgraded upstream package.
2. Build in Topological Order: Run the workspace-wide build and typecheck (npm run build --workspaces, pnpm -r run build, tsc -b, turbo run build typecheck, cargo check --workspace --all-targets) to verify that every downstream consumer compiles cleanly against the updated upstream package types.
3. Lockfile Deduplication: Run pnpm dedupe, yarn dedupe, or npm dedupe and inspect pnpm why <pkg> -r / cargo tree -d to confirm no unintended split resolutions remain across workspaces.