Sankofa/docs/guides/PNPM_MIGRATION_GUIDE.md

pnpm Migration Guide

This guide explains the package management setup for the Sankofa Phoenix project.

Current Status

The project supports both pnpm (recommended) and npm (fallback) for package management.

• Root: Uses pnpm with pnpm-lock.yaml
• API: Supports both pnpm and npm (via .npmrc configuration)
• Portal: Supports both pnpm and npm (via .npmrc configuration)

Why pnpm?

pnpm offers several advantages:

1. Disk Space Efficiency: Shared dependency store across projects
2. Speed: Faster installation due to content-addressable storage
3. Strict Dependency Resolution: Prevents phantom dependencies
4. Better Monorepo Support: Excellent for managing multiple packages

Installation

Using pnpm (Recommended)

# Install pnpm globally
npm install -g pnpm

# Or using corepack (Node.js 16.13+)
corepack enable
corepack prepare pnpm@latest --activate

# Install dependencies
pnpm install

# In API directory
cd api
pnpm install

# In Portal directory
cd portal
pnpm install

Using npm (Fallback)

# Install dependencies with npm
npm install

# In API directory
cd api
npm install

# In Portal directory
cd portal
npm install

CI/CD

The CI/CD pipeline (.github/workflows/ci.yml) supports both package managers:

- name: Install dependencies
  run: npm install --frozen-lockfile || pnpm install --frozen-lockfile

This ensures CI works regardless of which package manager is used locally.

Migration Steps (Optional)

If you want to fully migrate to pnpm:

1. Remove package-lock.json files (if any exist):

   find . -name "package-lock.json" -not -path "*/node_modules/*" -delete
   

2. Install with pnpm:

   pnpm install
   

3. Verify installation:

   pnpm list
   

4. Update CI/CD (optional):

   • The current CI already supports both, so no changes needed
   • You can make it pnpm-only if desired

Benefits of Current Setup

The current flexible setup provides:

• ✅ Backward Compatibility: Works with both package managers
• ✅ Team Flexibility: Team members can use their preferred tool
• ✅ CI Resilience: CI works with either package manager
• ✅ Gradual Migration: Can migrate at own pace

Recommended Practice

While both are supported, we recommend:

• Local Development: Use pnpm for better performance
• CI/CD: Current setup (both supported) is fine
• Documentation: Update to reflect pnpm as primary, npm as fallback

Troubleshooting

Module not found errors

If you encounter module resolution issues:

1. Delete node_modules and lock file
2. Reinstall with your chosen package manager:

   rm -rf node_modules package-lock.json
   pnpm install  # or npm install
   

Lock file conflicts

If you see conflicts between package-lock.json and pnpm-lock.yaml:

• Use .gitignore to exclude package-lock.json (already configured)
• Team should agree on primary package manager
• Document choice in README

---

Last Updated: 2025-01-09