fe0365757a
- Added generated index files and report directories to .gitignore to prevent unnecessary tracking of transient files. - Updated README links to reflect new documentation paths for better navigation. - Improved documentation organization by ensuring all links point to the correct locations, enhancing user experience and accessibility.
137 lines
3.0 KiB
Markdown
137 lines
3.0 KiB
Markdown
# 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
|
|
|