gru_emoney_token-factory/api/PNPM_SETUP.md

# pnpm Workspace Setup

This API project uses **pnpm** as the package manager with workspace support.

## Why pnpm?

- **Faster**: Up to 2x faster than npm
- **Disk efficient**: Shared dependency store
- **Strict**: Better dependency resolution
- **Workspace support**: Native monorepo support
- **Security**: Better handling of peer dependencies

## Installation

### Install pnpm

```bash
# Using npm
npm install -g pnpm

# Using curl (Linux/Mac)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Using Homebrew (Mac)
brew install pnpm

# Verify
pnpm --version
```

## Workspace Structure

The `api/` directory is a pnpm workspace containing:

```
api/
├── services/          # Service packages
├── shared/            # Shared utility packages
├── packages/          # Specification packages
└── tools/             # Development tool packages
```

## Workspace Configuration

- **pnpm-workspace.yaml**: Defines workspace packages
- **.npmrc**: pnpm configuration
- **.pnpmfile.cjs**: Workspace hooks for dependency management

## Common Commands

### Install Dependencies

```bash
# Install all workspace dependencies
cd api
pnpm install

# Install for specific package
cd api/services/rest-api
pnpm install
```

### Add Dependencies

```bash
# Add to specific package
cd api/services/rest-api
pnpm add express

# Add dev dependency to workspace root
cd api
pnpm add -D -w typescript

# Add workspace package
cd api/services/rest-api
pnpm add @emoney/blockchain
# (automatically uses workspace:*)
```

### Run Scripts

```bash
# Run script in specific package
cd api/services/rest-api
pnpm run dev

# Run script in all packages
cd api
pnpm -r run build

# Run script in filtered packages
cd api
pnpm --filter "@emoney/*" run test
```

### Build

```bash
# Build all packages
cd api
pnpm run build:all

# Build specific package
cd api/services/rest-api
pnpm run build
```

## Workspace Protocol

Internal packages use `workspace:*` protocol:

```json
{
  "dependencies": {
    "@emoney/blockchain": "workspace:*",
    "@emoney/validation": "workspace:*"
  }
}
```

This is automatically handled by `.pnpmfile.cjs`.

## Lock File

The `pnpm-lock.yaml` file should be committed to version control. It ensures:
- Consistent dependency versions across environments
- Reproducible builds
- Faster installs in CI/CD

## Troubleshooting

### Clear Cache

```bash
pnpm store prune
```

### Reinstall Everything

```bash
cd api
rm -rf node_modules
rm pnpm-lock.yaml
pnpm install
```

### Check Workspace

```bash
cd api
pnpm list -r --depth=0
```

## Migration from npm

If migrating from npm:

1. Remove `package-lock.json` files
2. Remove `node_modules` directories
3. Install with pnpm: `pnpm install`
4. Commit `pnpm-lock.yaml`

## CI/CD

### GitHub Actions Example

```yaml
- name: Setup pnpm
  uses: pnpm/action-setup@v2
  with:
    version: 8

- name: Setup Node.js
  uses: actions/setup-node@v3
  with:
    node-version: 18
    cache: 'pnpm'

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

- name: Build
  run: pnpm run build:all
```

## Resources

- [pnpm Documentation](https://pnpm.io/)
- [pnpm Workspaces](https://pnpm.io/workspaces)
- [pnpm CLI](https://pnpm.io/cli/add)