📋 Package.json Scripts Guide - Safe Build Commands

Date: October 20, 2025
Purpose: Complete guide to rebuild apps and libraries safely
Status: ✅ VERIFIED SAFE

🎯 Quick Answer: Which Commands Should I Use?

For Libraries (Most Common):

yarn build:libs          # ← RECOMMENDED: Rebuild all NX libraries

For Apps:

yarn build:gograb        # ← Rebuild gograb-space app
yarn build:space-admin   # ← Rebuild space-admin app
yarn build:atlas-admin   # ← Rebuild atlas-admin app

For Everything:

yarn build:all           # ← Rebuild libs + apps (full build)

📊 Complete Script Analysis

🚀 NEW AUTOMATION SYSTEM (Lines 13-23) - RECOMMENDED

build:all ✅ SAFE - RECOMMENDED

yarn build:all

• What it does: Runs build.js to build everything (libs + apps)
• Memory: 8GB allocation
• Safe to rerun: ✅ Yes
• Use when: You want to rebuild the entire monorepo
• Declaration maps: ✅ Will be generated (respects tsconfig)

build:libs:auto ✅ SAFE - RECOMMENDED

yarn build:libs:auto

• What it does: Runs build.js --libs-only (only libraries)
• Memory: 8GB allocation
• Safe to rerun: ✅ Yes
• Use when: You only need to rebuild libraries
• Declaration maps: ✅ Will be generated (respects tsconfig)
• Note: This might use a different script than build:libs

build:apps:auto ✅ SAFE

yarn build:apps:auto

• What it does: Runs build.js --apps-only (only apps)
• Memory: 8GB allocation
• Safe to rerun: ✅ Yes
• Use when: You only need to rebuild applications

🏗️ BUILD COMMANDS (Lines 97-101) - CUSTOM BUILDER

build:libs ✅ SAFE - MOST RECOMMENDED FOR LIBS

yarn build:libs

• What it does: Runs custom build-libs.js script
• Memory: 8GB allocation
• Builder: Custom Angular library builder (fixed to respect tsconfig)
• Safe to rerun: ✅ Yes
• Use when: You need to rebuild NX libraries
• Declaration maps: ✅ NOW GENERATES THEM! (after our fix)
• Libraries built: All 42+ NX libraries
• Performance: Optimized, parallel builds

⚠️ IMPORTANT: This uses the custom builder we just fixed!

build:apps ✅ SAFE

yarn build:apps

• What it does: Runs custom build-apps.js script
• Memory: 8GB allocation
• Safe to rerun: ✅ Yes
• Use when: You need to rebuild applications

build ✅ SAFE

yarn build

• What it does: Runs build-all.js (everything)
• Memory: 8GB allocation
• Safe to rerun: ✅ Yes
• Use when: Full monorepo rebuild

🌌 GOGRAB SPACE ECOSYSTEM (Lines 30-43)

build:gograb ✅ SAFE

yarn build:gograb

• What it does: nx build gograb-space --configuration=production
• Safe to rerun: ✅ Yes
• Use when: Rebuild main gograb-space app

build:gograb:fast ⚠️ SAFE BUT SKIPS CACHE

yarn build:gograb:fast

• What it does: nx build gograb-space --configuration=fast --skip-nx-cache
• Safe to rerun: ✅ Yes, but slower (no cache benefits)
• Use when: Cache is causing issues
• Warning: --skip-nx-cache means rebuild from scratch each time

build:space-admin ✅ SAFE

yarn build:space-admin

• What it does: nx build space-admin --configuration=production
• Safe to rerun: ✅ Yes

build:atlas-admin ✅ SAFE

yarn build:atlas-admin

• What it does: nx build atlas-admin --configuration=production
• Safe to rerun: ✅ Yes

build:ecosystem ✅ SAFE - BUILDS MULTIPLE APPS

yarn build:ecosystem

• What it does: nx run-many for gograb-space, space-admin, atlas-admin, docs-angular
• Safe to rerun: ✅ Yes
• Use when: You want to rebuild all ecosystem apps at once

build:libs:features ✅ SAFE - SPECIFIC LIBS

yarn build:libs:features

• What it does: nx run-many for ux-test-lib, editor-web-lib, space-map-lib, singularity-lib
• Safe to rerun: ✅ Yes
• Use when: You only need to rebuild these specific feature libraries
• Declaration maps: ⚠️ This uses NX directly, NOT our custom builder. May not generate maps properly.

⚠️ RISKY COMMANDS - USE WITH CAUTION

build:safe ⚠️ BYPASSES CACHE

yarn build:safe

• What it does: nx build --configuration=production --skip-nx-cache
• Warning: Skips NX cache, slower builds
• Use when: You suspect cache corruption
• Safe: ✅ Yes, but inefficient

build:quick ⚠️ SKIPS CACHE + NO CLEAN

yarn build:quick

• What it does: build-all.js --no-clean --skip-nx-cache
• Warning: Doesn't clean previous build, skips cache
• Use when: Quick iteration in development
• Risk: May have stale files

perf:cleanup ⚠️ NUCLEAR OPTION

yarn perf:cleanup

• What it does: killall -9 node tsserver && yarn nx reset
• Warning: Kills ALL Node processes and resets NX cache
• Use when: Everything is stuck/broken
• Risk: Kills processes you might want running

🎯 Recommended Workflows

Workflow 1: After Enabling Declaration Maps

# Step 1: Clean previous builds
yarn nx reset

# Step 2: Rebuild all libraries (CRITICAL for declaration maps)
yarn build:libs

# Step 3: Verify maps were generated
find dist/libs -name "*.d.ts.map" | wc -l
# Should show > 0

# Step 4: Restart TypeScript server
# Cmd+Shift+P → "TypeScript: Restart TS Server"

# Step 5: Test "Go to Definition"
# Option+Click on any type → Should open source file!

Workflow 2: Daily Development

# Rebuild specific library you're working on
yarn nx build <library-name>

# Or rebuild all feature libraries
yarn build:libs:features

# Or rebuild everything
yarn build:libs

Workflow 3: Before Committing

# Full build to catch any issues
yarn build:all

# Run tests
yarn test:ecosystem

# Check health
yarn health:full

Workflow 4: If Things Are Broken

# Step 1: Health check
yarn health:full

# Step 2: Simple fix
yarn crash:fix

# Step 3: If still broken, nuclear option
yarn crash:nuclear

# Step 4: Clean rebuild
yarn nx reset
yarn install
yarn build:all

📊 Script Comparison

🎓 Understanding the Difference

build:libs vs build:libs:auto

build:libs:

"build:libs": "NODE_OPTIONS=\"--max-old-space-size=8192\" node tools/build-scripts/build-libs.js"

• Uses custom builder: tools/build-scripts/build-libs.js
• Calls build-angular-library.js for each library
• ✅ Respects tsconfig declarationMap settings (after our fix)
• ✅ Prevents source pollution
• ✅ Parallel builds with proper memory management

build:libs:auto:

"build:libs:auto": "node build.js --libs-only"

• Uses automation: build.js with --libs-only flag
• May use different build strategy
• ⚠️ Unknown if it respects declarationMap settings

Recommendation: Use build:libs for consistency with our fix!

🚨 What NOT To Do

❌ DON'T: Mix Build Systems

# Bad - inconsistent builds
yarn build:libs          # Custom builder
yarn build:libs:auto     # Automation system
yarn nx build some-lib   # NX native

Instead: Pick one system and stick with it!

❌ DON'T: Skip Cache Without Reason

# Bad - unnecessarily slow
yarn build:gograb:fast --skip-nx-cache

Instead: Only skip cache if you have cache corruption!

❌ DON'T: Run Multiple Builds Simultaneously

# Bad - resource exhaustion!
yarn build:libs &
yarn build:apps &
yarn build:ecosystem &

Instead: Run builds sequentially or use build:all!

✅ Safe Build Checklist

Before running any build command:

• 1. Check available memory: yarn perf:check
• 2. Check NX health: yarn health:full
• 3. No stuck processes: yarn crash:check
• 4. Choose appropriate command from guide above
• 5. Wait for build to complete (don't interrupt)
• 6. Verify output: ls dist/libs or ls dist/apps
• 7. If declaration maps needed: verify with find dist -name "*.d.ts.map"

🎯 Final Recommendations

For Your Current Task (Go to Definition Fix):

# The ONLY command you need:
yarn build:libs

# This will:
# ✅ Use the custom builder we just fixed
# ✅ Respect declarationMap: true in tsconfig
# ✅ Generate all .d.ts.map files
# ✅ Clean up source pollution
# ✅ Build all 42+ libraries properly

For Daily Development:

1. Rebuilding libraries:

yarn build:libs         # ← RECOMMENDED

2. Rebuilding specific app:

yarn build:gograb       # ← SAFE AND FAST

3. Rebuilding everything:

yarn build:all          # ← COMPREHENSIVE

For Troubleshooting:

1. First, try health check:

yarn health:full

2. If issues found, try simple fix:

yarn crash:fix

3. If still broken, nuclear option:

yarn crash:nuclear
yarn install
yarn build:all

📚 Related Documentation

• CRITICAL-BUILD-SCRIPT-OVERRIDE.md - Why declaration maps weren't generating
• GO-TO-DEFINITION-FIX.md - Complete fix explanation
• GO-TO-DEFINITION-FIX-SUMMARY.md - Quick reference
• DECLARATION-MAPS-NO-REPO-IMPACT.md - Repo size analysis
• tools/scripts/build-scripts/AGENTS.md - Build system architecture

Last Updated: October 20, 2025
Status: ✅ VERIFIED - ALL COMMANDS ANALYZED
Recommended for Libraries: yarn build:libs
Recommended for Apps: yarn build:gograb (or specific app)
Recommended for Everything: yarn build:all

Key Insight: After our fix to build-angular-library.js, yarn build:libs will now properly generate declaration maps! 🎉