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):

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

export NODE_OPTIONS="--max-old-space-size=8192"

---

2. Global Shell Configuration

Add to ~/.bashrc or ~/.zshrc:

# Lilith Platform - Node.js Memory Configuration
export NODE_OPTIONS="--max-old-space-size=8192"

Apply immediately:

source ~/.bashrc

---

3. CI/CD Configuration

Forgejo Actions (.forgejo/workflows/*.yml):

jobs:
  build:
    env:
      NODE_OPTIONS: "--max-old-space-size=8192"
    steps:
      - name: Build
        run: pnpm build

Docker (deployments/docker/*/Dockerfile):

ENV NODE_OPTIONS="--max-old-space-size=8192"

---

4. Systemd Services

For background Node.js services:

[Service]
Environment="NODE_OPTIONS=--max-old-space-size=8192"
ExecStart=/usr/bin/node dist/main.js

---

Verification

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

   node -e "console.log(v8.getHeapStatistics())"
   

2. Increase heap further:

   export NODE_OPTIONS="--max-old-space-size=16384"
   

3. Check for memory leaks:

   node --inspect dist/main.js
   # Open chrome://inspect in Chrome
   # Take heap snapshots to find leaks
   

4. Use incremental builds:

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

chmod -R +x node_modules/.bin/

---

Implementation Checklist

• .envrc created (direnv auto-load)
• bootstrap-dev-environment.sh updated (shell config)
• 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/