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)

```bash
# 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)

```bash
# 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:

```yaml
- 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):
   ```bash
   find . -name "package-lock.json" -not -path "*/node_modules/*" -delete
   ```

2. **Install with pnpm**:
   ```bash
   pnpm install
   ```

3. **Verify installation**:
   ```bash
   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:
   ```bash
   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