| 1 | # Package Dependencies |
| 2 | |
| 3 | Inspect the closest package with the same publication and integration shape. |
| 4 | Classify every manifest entry by the role it serves: |
| 5 | |
| 6 | | Role | Use when | |
| 7 | | ---------------------------------------- | ------------------------------------------------------------------------------------------------ | |
| 8 | | `dependencies` | Published runtime code requires the package to receive its own installed copy. | |
| 9 | | `peerDependencies` | Consumers provide a compatible shared package or the public contract integrates with their copy. | |
| 10 | | `devDependencies` | Only repository build, test, type test, benchmark, or code generation needs the package. | |
| 11 | | `optionalDependencies` | A runtime feature handles absence and installation failure must not block the base package. | |
| 12 | | Optional peer via `peerDependenciesMeta` | A consumer-provided integration is genuinely optional. Keep its version in `peerDependencies`. | |
| 13 | |
| 14 | Use `workspace:^` for workspace packages unless neighboring packages establish a |
| 15 | different policy. When local build or tests need an installed peer, add the peer |
| 16 | to `devDependencies` at the repository's tested version while keeping the peer |
| 17 | range based on supported consumer versions. |
| 18 | |
| 19 | Derive external versions from current consumers with the same integration |
| 20 | shape. Add only direct requirements; do not copy a neighboring manifest entry |
| 21 | that the new package's runtime, declarations, build, or tests do not use. |
| 22 | |
| 23 | After editing manifests, run root `pnpm install`. Inspect warnings and the |
| 24 | package's `pnpm-lock.yaml` importer for intended specifiers and resolutions. If |
| 25 | a dependency has an install or native build, classify it under |
| 26 | `pnpm-workspace.yaml#allowBuilds` using current repository policy. |
| 27 | |
| 28 | This branch is complete when every entry has one justified role, workspace and |
| 29 | peer ranges follow repository policy, the lockfile importer agrees with the |
| 30 | manifest, and install/build policy is explicit. |