# pnpm Setup Guide

## Why pnpm?

pnpm is a fast, disk space efficient package manager that:
- **Saves disk space**: Uses hard links and symlinks to share packages
- **Faster**: Parallel downloads and efficient dependency resolution
- **Strict**: Better dependency management and security
- **Monorepo support**: Built-in workspace support

## Installation

### Option 1: Using Corepack (Recommended)

Corepack is included with Node.js 16.9+ and manages package managers:

```bash
# Enable corepack
corepack enable

# Prepare and activate pnpm
corepack prepare pnpm@latest --activate

# Verify installation
pnpm --version
```

### Option 2: Using npm

```bash
npm install -g pnpm
```

### Option 3: Using Homebrew (macOS)

```bash
brew install pnpm
```

### Option 4: Using Standalone Script

```bash
curl -fsSL https://get.pnpm.io/install.sh | sh -
```

## Quick Start

```bash
# Install dependencies
pnpm install

# Run development server
pnpm dev

# Build for production
pnpm build

# Run production server
pnpm start
```

## Common Commands

### Package Management
```bash
# Install dependencies
pnpm install

# Add a dependency
pnpm add <package>

# Add a dev dependency
pnpm add -D <package>

# Remove a dependency
pnpm remove <package>

# Update dependencies
pnpm update
```

### Scripts
```bash
# Run a script
pnpm <script-name>

# Run with arguments
pnpm <script-name> -- --arg value
```

### Other Useful Commands
```bash
# Check for outdated packages
pnpm outdated

# Audit for security vulnerabilities
pnpm audit

# List installed packages
pnpm list

# Clean install (remove node_modules and reinstall)
pnpm install --force
```

## Configuration

The project includes `.npmrc` with pnpm-specific settings:

- `auto-install-peers=true` - Automatically install peer dependencies
- `strict-peer-dependencies=false` - Allow missing peer dependencies
- `shamefully-hoist=false` - Use strict dependency resolution
- `public-hoist-pattern` - Hoist specific packages for compatibility

## Benefits for This Project

1. **Faster installs**: pnpm is typically 2-3x faster than npm
2. **Disk space**: Saves significant disk space with shared packages
3. **Better security**: Strict dependency resolution prevents phantom dependencies
4. **Lock file**: `pnpm-lock.yaml` ensures reproducible installs

## Migration from npm

If you were using npm before:

```bash
# Remove npm lock file
rm package-lock.json

# Remove node_modules
rm -rf node_modules

# Install with pnpm
pnpm install
```

## Troubleshooting

### Permission Issues
```bash
# Use pnpm's store in a writable location
pnpm config set store-dir ~/.pnpm-store
```

### Clear Cache
```bash
pnpm store prune
```

### Reset Everything
```bash
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

## CI/CD Integration

### GitHub Actions
```yaml
- uses: pnpm/action-setup@v2
  with:
    version: 8
- uses: actions/setup-node@v3
  with:
    node-version: 18
    cache: 'pnpm'
- run: pnpm install --frozen-lockfile
```

### Docker
```dockerfile
FROM node:18-alpine
RUN corepack enable && corepack prepare pnpm@latest --activate
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
```

## Resources

- [pnpm Documentation](https://pnpm.io/)
- [pnpm GitHub](https://github.com/pnpm/pnpm)
- [Why pnpm?](https://pnpm.io/motivation)

