📚 Multi-Monorepo Configuration - Complete Documentation Index

This directory contains all documentation and tools for the multi-monorepo performance optimization.

📖 Documentation Files

1. SETUP-COMPLETE.md - Quick Start Guide

• ✅ Summary of what was configured
• 🚀 Next steps to complete setup
• 🧪 Testing and verification
• ⏱️ Read time: 3 minutes

2. MULTI-MONOREPO-SETUP.md - Technical Details

• 📊 Complete configuration details
• 🔧 Troubleshooting guide
• 💡 Best practices
• 🎯 Performance recommendations
• ⏱️ Read time: 10 minutes

3. ROLLBACK-MULTI-MONOREPO.md - Revert Instructions

• 🔄 Complete step-by-step rollback guide
• ✅ Verification checklist
• 🆘 Troubleshooting rollback issues
• 💾 Backup and restore procedures
• ⏱️ Read time: 15 minutes
• ⚠️ Important: Read this before reverting any changes!

4. FIX-FILE-LIMITS.md - File Descriptor Limits Fix

• 🔧 Fixes "EMFILE: too many open files" errors
• 📊 Increases macOS file descriptor limits
• 🔄 Includes complete rollback instructions
• 🚀 Required for multi-monorepo development
• ⏱️ Read time: 10 minutes
• ⚠️ Critical: Must be applied for Git operations to work properly

5. ADD_TO_ZSHRC.txt - Shell Configuration

• 🐚 Shell environment variables
• 🔧 Useful aliases
• 📋 Copy-paste ready
• ⚠️ Already applied to your ~/.zshrc

🛠️ Scripts and Tools

Configuration Scripts

Located in scripts/ directory:

1. configure-multi-monorepo.js

yarn configure:multi-monorepo

• Sets EventEmitter max listeners to 30
• Applies multi-monorepo optimizations
• Run this after shell restarts if needed

2. verify-multi-monorepo-setup.js

yarn verify:multi-monorepo

• Checks all configuration settings
• Verifies environment variables
• Reports system status
• Shows recommendations

3. quick-rollback.sh

bash scripts/quick-rollback.sh

• ⚠️ Use with caution!
• Automated rollback script
• Creates backups before changes
• See ROLLBACK-MULTI-MONOREPO.md for full instructions

4. apply-file-limits.sh

bash scripts/apply-file-limits.sh

• 🔧 Required for file descriptor limits
• Increases macOS file limits (256 → 65,536)
• Requires sudo password
• Fixes "too many open files" errors
• See FIX-FILE-LIMITS.md for details

🚀 Quick Command Reference

Setup & Configuration

# Verify current configuration
yarn verify:multi-monorepo

# Apply multi-monorepo settings
yarn configure:multi-monorepo

# Reset Nx daemon
yarn nx reset

Monitoring

# Check running Nx processes
monorepo-status

# Check environment variables
echo $NODE_OPTIONS
echo $UV_THREADPOOL_SIZE

Maintenance

# Reset all Nx caches across monorepos
nx-reset-all

# Clean up Nx daemons
monorepo-clean

📊 What Was Configured

✅ Cursor/VSCode Settings

• TypeScript server: 8GB max memory
• Large files: 4GB support
• Optimized file watchers
• Location: .vscode/settings.json

✅ Nx Configuration

• Max parallel tasks: 3
• Max memory: 16GB
• Daemon concurrency: 6
• Location: nx.json

✅ Node.js Environment

• Max heap size: 8GB
• Thread pool: 128 threads
• EventEmitter listeners: 30
• Location: ~/.zshrc

✅ macOS File Descriptor Limits

• System soft limit: 65,536 (was 256)
• System hard limit: 200,000
• Per-process limit: 65,536
• Location: ~/Library/LaunchAgents/limit.maxfiles.plist

✅ Applied To

• /Users/fguijarro/developer/repos/editor
• /Users/fguijarro/developer/repos/editor2
• /Users/fguijarro/developer/repos/gograb-space

🎯 When to Use What

⚠️ Important Notes

Before Rollback

• ✅ Read ROLLBACK-MULTI-MONOREPO.md completely
• ✅ Create backups of your customizations
• ✅ Close all Cursor windows
• ✅ Stop all development servers

After Configuration

• ✅ Restart Cursor completely
• ✅ Verify settings with yarn verify:multi-monorepo
• ✅ Test with your normal workflow
• ✅ Monitor system resources initially

Regular Maintenance

• 🔄 Run yarn nx reset weekly
• 📊 Monitor memory usage
• 🧹 Clean up unused Cursor windows
• 🔍 Check for stale processes with monorepo-status

🆘 Getting Help

Quick Checks

1. Environment variables not set?

   source ~/.zshrc
   echo $NODE_OPTIONS
   

2. Still seeing MaxListenersExceededWarning?

   yarn configure:multi-monorepo
   # Then restart Cursor
   

3. Seeing "EMFILE: too many open files" errors?

   # Apply file limits fix (requires password)
   bash scripts/apply-file-limits.sh
   # Then restart Cursor
   # See FIX-FILE-LIMITS.md for details
   

4. Cursor running slow?

   yarn nx reset
   # Close unused Cursor windows
   

Full Verification

cd /Users/fguijarro/developer/repos/editor
yarn verify:multi-monorepo

📈 Expected Performance Improvements

🏗️ System Profile

Optimized For:

• Machine: MacBook Pro / Mac Studio / iMac Pro
• RAM: 128GB (you have plenty!)
• CPU: Multi-core Apple Silicon or Intel
• Workload: 2-3 monorepos simultaneously

Not Recommended For:

• Machines with < 16GB RAM
• Single monorepo workflows
• Shared/CI environments

📝 Change Log

October 18, 2025

• ✅ Initial multi-monorepo optimization
• ✅ Applied to 3 monorepos
• ✅ Shell configuration added
• ✅ File descriptor limits fix added
• ✅ Documentation created
• ✅ Rollback guide provided (includes file limits rollback)

🔗 File Structure

editor/
├── docs/english/public/development/monorepo/
│   ├── SETUP-COMPLETE.md              # Quick start (read first!)
│   ├── MULTI-MONOREPO-SETUP.md        # Technical details
│   ├── ROLLBACK-MULTI-MONOREPO.md     # Revert instructions
│   ├── FIX-FILE-LIMITS.md             # File descriptor limits fix
│   ├── MULTI-MONOREPO-INDEX.md        # This file
│   └── ADD_TO_ZSHRC.txt               # Shell configuration
├── .vscode/
│   └── settings.json              # Cursor settings (modified)
├── nx.json                        # Nx configuration (modified)
├── package.json                   # Scripts added
├── ~/Library/LaunchAgents/
│   └── limit.maxfiles.plist       # macOS file limits (created)
└── scripts/
    ├── configure-multi-monorepo.js    # Configuration script
    ├── verify-multi-monorepo-setup.js # Verification script
    ├── quick-rollback.sh              # Automated rollback
    └── apply-file-limits.sh           # File limits fix script

Last Updated: October 18, 2025
Configuration Version: 1.0
Machine Profile: High-performance workstation (128GB RAM)
Status: ✅ Active and configured