migrate-pnpm.md

Plan: Migrate from Yarn to pnpm (v10.28.1)

Migrate the monorepo from Yarn 4.x to pnpm 10.28.1. This migration enforces strict dependency management by fixing ghost dependencies individually, updating Dockerfiles, and migrating GitHub Actions.

Steps

1. GitIgnore: Add .pnpm-store to .gitignore.
2. Enforce pnpm v10: Update root package.json with "packageManager": "pnpm@10.28.1" and set engines.
3. Consolidate Overrides: Move all resolutions from the root and sub-package package.json files into the pnpm.overrides section of the root package.json.
4. Migrate Scripts: Replace yarn workspace <pkg> <cmd> with pnpm --filter <pkg> <cmd> and all other yarn calls with pnpm in all package.json files.
5. Update Dockerfiles: Modify Dockerfile and Dockerfile to install pnpm@10.28.1 and use pnpm dlx turbo and pnpm install --frozen-lockfile.
6. Update CI/CD Workflows: Update shared and specific workflows in .github/workflows/ to use pnpm using corepack, set cache: "pnpm", and replace yarn commands.
7. Fix Ghost Dependencies: Execute pnpm install and pnpm -r build. For every "module not found" error, explicitly add the missing dependency until all builds succeed without using public-hoist-pattern.
8. Artifact Cleanup: Delete .yarn, .yarnrc.yml, and yarn.lock.
9. Minor Fixes: Upgrade vscode settings and all README.md to reflect changes.
10. Dependency Check Removal: Remove dependency-check from devDependencies and eliminate any related build scripts in all package.json files.

Add these settings to pnpm-workspace.yaml

cleanupUnusedCatalogs: false
linkWorkspacePackages: true
packageImportMethod: clone-or-copy

Important: when adding missing dependencies, use pnpm add or pnpm add -D instead of manually editing package.json files to ensure proper lockfile updates.

Important: once done, run pnpm test in loop at the root of the monorepo and fix any issues until all tests pass successfully across the monorepo.

When modifying Dockerfiles and/or GitHub Actions workflows, prefer to use corepack to install pnpm instead of installing it via npm: pnpm version is specified in the root package.json file.

Further Considerations

1. pnpm-workspace.yaml: Verify that the existing pnpm-workspace.yaml correctly covers all apps/* and packages/* folders.
2. CI Cache Keys: Ensure that the cache-dependency-path in GitHub Actions points to pnpm-lock.yaml to ensure reliable caching after the migration.
3. Peer Dependency Issues: pnpm 10 is strict about peer dependencies; some packages might require pnpm.peerDependencyRules in the root package.json if upstream packages have poorly defined peers.