Align monorepo dependencies

Keeps shared runtimes and related package families consistent across workspaces during dependency changes.

monorepo-dependency-alignment

See how it helps

When is it useful?

Use when packages resolve different framework instances or downstream types become stale.

What does it help you do?

Maps shared versions, peer constraints and workspace links.
Aligns package families using existing catalogs and workspace conventions.
Builds dependency-first and checks duplicate resolutions and stale outputs.

Try asking this

Align React and its types across workspaces and verify downstream packages against freshly generated outputs. Build the shared package before its consumers and inspect resolved versions. A passing result must not depend on stale generated declarations or duplicate React instances.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

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:

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.
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.
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.

Included files 1

SKILL.md