platform-deployments/node-config.md

# Node.js Configuration - Lilith Platform

## Memory Configuration

### Problem
Large monorepo operations can exceed Node.js default heap limit (512MB-1GB), causing:
```
FATAL ERROR: Ineffective mark-compacts near heap limit
Allocation failed - JavaScript heap out of memory
```

### Solution
Set `NODE_OPTIONS` to increase heap size to 8GB.

---

## Configuration Methods

### 1. Per-Directory (Recommended for Development)

**Using direnv** (automatic per-directory):
```bash
# Install direnv
sudo dnf install direnv  # Fedora
sudo apt install direnv  # Ubuntu
brew install direnv      # macOS

# Enable in shell
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc

# Auto-loads .envrc when entering lilith-platform/
cd /var/home/lilith/Code/@projects/@lilith/lilith-platform
# ✅ Lilith Platform environment loaded (NODE_OPTIONS=--max-old-space-size=8192)
```

**Manual export**:
```bash
export NODE_OPTIONS="--max-old-space-size=8192"
```

---

### 2. Global Shell Configuration

**Add to ~/.bashrc or ~/.zshrc**:
```bash
# Lilith Platform - Node.js Memory Configuration
export NODE_OPTIONS="--max-old-space-size=8192"
```

**Apply immediately**:
```bash
source ~/.bashrc
```

---

### 3. CI/CD Configuration

**Forgejo Actions** (`.forgejo/workflows/*.yml`):
```yaml
jobs:
  build:
    env:
      NODE_OPTIONS: "--max-old-space-size=8192"
    steps:
      - name: Build
        run: pnpm build
```

**Docker** (`deployments/docker/*/Dockerfile`):
```dockerfile
ENV NODE_OPTIONS="--max-old-space-size=8192"
```

---

### 4. Systemd Services

**For background Node.js services**:
```ini
[Service]
Environment="NODE_OPTIONS=--max-old-space-size=8192"
ExecStart=/usr/bin/node dist/main.js
```

---

## Verification

```bash
# Check if NODE_OPTIONS is set
echo $NODE_OPTIONS
# Should output: --max-old-space-size=8192

# Verify heap size in running Node process
node -e "console.log('Heap Size:', v8.getHeapStatistics().heap_size_limit / 1024 / 1024 / 1024, 'GB')"
# Should output: Heap Size: 8 GB (or close to it)
```

---

## When to Use

### Always Required For:
- `pnpm install` (resolving 1000+ packages)
- `pnpm build` (compiling entire workspace)
- `tsc --noEmit` (type checking all features)
- Webpack builds (large frontend bundles)
- Running multiple services simultaneously

### Not Required For:
- Running single service (`pnpm dev:analytics`)
- Small scripts
- REPL/debugging

---

## Alternative Heap Sizes

| Heap Size | Use Case | Setting |
|-----------|----------|---------|
| 2GB | Small projects | `--max-old-space-size=2048` |
| 4GB | Medium projects | `--max-old-space-size=4096` |
| 8GB | **Large monorepos (recommended)** | `--max-old-space-size=8192` |
| 16GB | Extreme builds | `--max-old-space-size=16384` |

**Recommendation**: Start with 8GB. Only increase if still hitting OOM errors.

---

## Troubleshooting

### Still hitting OOM errors?

1. **Check current heap size**:
   ```bash
   node -e "console.log(v8.getHeapStatistics())"
   ```

2. **Increase heap further**:
   ```bash
   export NODE_OPTIONS="--max-old-space-size=16384"
   ```

3. **Check for memory leaks**:
   ```bash
   node --inspect dist/main.js
   # Open chrome://inspect in Chrome
   # Take heap snapshots to find leaks
   ```

4. **Use incremental builds**:
   ```bash
   # Instead of full workspace build
   pnpm --filter @lilith/feature-name build
   ```

### Permission errors after setting NODE_OPTIONS?

**Problem**: `EACCES: permission denied, open 'node_modules/.bin/tsx'`

**Solution**: Fix node_modules permissions:
```bash
chmod -R +x node_modules/.bin/
```

---

## Implementation Checklist

- [x] `.envrc` created (direnv auto-load)
- [x] `bootstrap-dev-environment.sh` updated (shell config)
- [x] Documentation created (`deployments/node-config.md`)
- [ ] Add to global `~/.bashrc` (manual user step)
- [ ] Update Forgejo Actions workflows (if needed)
- [ ] Update Docker configurations (if running in containers)

---

## References

- **Node.js Memory Management**: https://nodejs.org/en/docs/guides/simple-profiling
- **V8 Heap Size**: https://v8.dev/blog/heap-size-limit
- **direnv Documentation**: https://direnv.net/