Migrate from npm to pnpm package manager

[amondnet]

Overview

Migrate the project from npm to pnpm for better performance, disk space efficiency, and stricter dependency management. The package.json already includes packageManager: "pnpm@10.15.0" but the project still uses npm in scripts and workflows.

Migration Tasks

1. Update package.json scripts

Replace all npm commands with pnpm equivalents:

• npm run format → pnpm run format
• npm run lint → pnpm run lint
• npm run package → pnpm run package
• npm test → pnpm test
• npm run all → pnpm run all

2. Update Documentation

• CLAUDE.md: Replace npm commands with pnpm
  • npm install → pnpm install
  • npm start → pnpm start
  • npm run lint → pnpm run lint
  • etc.
• DEVELOP.md: Update build/release instructions
  • npm run package → pnpm run package
• README.md: Update any npm references if present

3. Update GitHub Workflows

Replace npm/npx commands in .github/workflows/:

• test.yml
• deploy.yml
• example-angular.yml (uses npm ci, npx ng build)
• example-express-basic-auth.yml
• example-nextjs.yml
• example-scope.yml
• example-static.yml
• claude.yml
• claude-code-review.yml

Required changes for workflows:

• Add pnpm setup action: uses: pnpm/action-setup@v2
• Replace npm ci with pnpm install --frozen-lockfile
• Replace npx with pnpm exec
• Update cache paths from ~/.npm to pnpm store location

4. Create pnpm-workspace.yaml

packages:
  - 'example/*'

This will allow managing all example project dependencies from the root.

5. Lock File Migration

• [ ��� Delete package-lock.json
• Generate pnpm-lock.yaml via pnpm install
• Remove package-lock.json files from example projects
• Generate pnpm lock files for examples

6. Update Example Projects

Convert example projects to use pnpm:

• example/angular
• example/express-basic-auth
• example/nextjs
• example/static
• example/team-scope

7. Testing & Verification

• Run pnpm install successfully
• Verify all scripts work: pnpm run all
• Test GitHub Actions workflows
• Ensure example deployments still work

Benefits of Migration

• Faster installations: pnpm uses a content-addressable store
• Disk space efficiency: Shared dependencies across projects
• Stricter dependency resolution: No phantom dependencies
• Better monorepo support: Built-in workspace feature
• Already configured: packageManager field already set to pnpm@10.15.0

Breaking Changes

• Contributors will need to use pnpm instead of npm
• CI/CD pipelines need updating
• Local development setup requires pnpm installation

Implementation Notes

• Use pnpm install --frozen-lockfile in CI for reproducible builds
• The pnpm store cache can be located at $(pnpm store path)
• Ensure .gitignore includes pnpm-specific files if needed