Build Scripts Documentation

🏗️ Overview

These scripts provide comprehensive build automation for our NX monorepo, handling libraries, applications, and complex build scenarios with intelligent fallback strategies.

📁 Available Build Scripts

1. build-all.js - Unified Build Process

Purpose: Single entry point for building all libraries and applications in the correct order.

Usage:

# Build everything
node tools/scripts/build-scripts/build-all.js

# Build with specific options
node tools/scripts/build-scripts/build-all.js --skip-nx-cache --continue-on-error

# Build only libraries
node tools/scripts/build-scripts/build-all.js --libs-only

# Build only applications
node tools/scripts/build-scripts/build-all.js --apps-only

# Build specific target
node tools/scripts/build-scripts/build-all.js core-types

# Development build
node tools/scripts/build-scripts/build-all.js --dev

Options:

• --skip-nx-cache: Skip NX cache
• --continue-on-error: Continue building even if some targets fail
• --quiet: Reduce output verbosity
• --dev: Development build (default is production)
• --no-clean: Skip cleaning dist directory
• --libs-only: Build only libraries
• --apps-only: Build only applications
• --strategy=nx-direct: Use direct NX commands
• --strategy=manual: Use manual build approach
• --strategy=custom-order: Use custom build order

2. build-libs.js - Library Build Script

Purpose: Builds all libraries in the correct dependency order with intelligent error handling.

Usage:

# Build all libraries
node tools/scripts/build-scripts/build-libs.js

# Build specific library
node tools/scripts/build-scripts/build-libs.js core-types

# Build with options
node tools/scripts/build-scripts/build-libs.js --skip-nx-cache --continue-on-error --dev

Library Build Order:

1. core-types - Base types and interfaces
2. core - Core functionality
3. theme-runtime - Theme runtime system
4. theme-styles - Theme styling
5. theme-dev-tools - Theme development tools
6. theme-showcase - Theme showcase components
7. ux-menu - UX menu components
8. ux-panel - UX panel components
9. ux-ui-extended - Extended UI components
10. shared-ui - Shared UI components
11. widgets - Widget system
12. editor-ui - Editor UI components
13. unified-nav - Unified navigation

Features:

• Automatic dependency resolution
• TypeScript patching to prevent destructuring errors
• Theme error fixing
• Fallback build methods for problematic libraries
• Comprehensive error reporting

3. build-apps.js - Application Build Script

Purpose: Builds Angular applications using multiple strategies to ensure success.

Usage:

# Build all applications
node tools/scripts/build-scripts/build-apps.js

# Build specific application
node tools/scripts/build-scripts/build-apps.js docs-angular

# Build with different strategies
node tools/scripts/build-scripts/build-apps.js --strategy=nx-direct
node tools/scripts/build-scripts/build-apps.js --strategy=manual
node tools/scripts/build-scripts/build-apps.js --strategy=ng-direct

Applications:

• docs-angular (port: 5010)
• space-map (port: 5100)
• editor-web (port: 5200)
• ux-test (port: 5300)
• singularity (port: 5400)

Build Strategies:

• Auto: Tries multiple approaches in sequence
• NX Direct: Uses direct NX commands
• Manual: Bypasses project graph issues
• NG Direct: Uses Angular CLI directly

Features:

• TypeScript module patching
• Project graph generation
• Multiple fallback strategies
• Custom cache directory handling
• Comprehensive error recovery

4. clean-dist.js - Clean Build Outputs

Purpose: Cleans the dist directory before builds.

Usage:

# Clean all dist directories
node tools/scripts/build-scripts/clean-dist.js

# Clean specific target
node tools/scripts/build-scripts/clean-dist.js --target=core-types

# Quiet mode
node tools/scripts/build-scripts/clean-dist.js --quiet

Options:

• --target=<name>: Clean specific library/app
• --quiet: Reduce output verbosity

5. copy-lib.js - Library Copy Fallback

Purpose: Fallback method to build libraries by copying files when NX build fails.

Usage:

# Copy library files as fallback build
node tools/scripts/build-scripts/copy-lib.js core-types
node tools/scripts/build-scripts/copy-lib.js theme-system

What it does:

• Copies source files to dist directory
• Creates index.js and index.d.ts files
• Excludes test files
• Maintains directory structure

6. final-build-fix.js - Build Fixes

Purpose: Applies final fixes after build process.

Usage:

# Apply build fixes
node tools/scripts/final-build-fix.js

What it does:

• Fixes path mappings in tsconfig.base.json
• Creates symlinks from dist to node_modules
• Builds core-types library
• Builds editor-web with skip lib check

🔧 Build Configuration

Environment Variables

# Use alternative cache directory
NX_CACHE_DIRECTORY=/tmp/nx-cache

# Skip NX cache
--skip-nx-cache

# Continue on error
--continue-on-error

Build Strategies

1. Standard NX Build: Uses nx build command
2. Direct NX Run: Uses nx run with specific targets
3. Manual Approach: Bypasses project graph issues
4. Angular CLI Direct: Uses ng build directly
5. Copy Method: Copies files as fallback

🛠️ Special Build Handling

Problematic Libraries

Some libraries require special handling:

• editor-ui: Uses custom build script
• theme-system: Uses copy method to avoid project graph issues
• gograb-ai: Has custom build process

TypeScript Patching

The scripts automatically patch TypeScript to prevent common errors:

// Patches getReferencedFiles to avoid destructuring errors
// Patches findConfigFile for better error handling
// Applies safety checks for file references

Theme Error Fixing

Automatic fixes for common theme system errors:

• Return type annotations
• Object property access with type assertions
• Observable type improvements

🚀 Quick Start Examples

Complete Build Process

# Clean and build everything
node tools/scripts/build-scripts/clean-dist.js
node tools/scripts/build-scripts/build-all.js

# Build with error recovery
node tools/scripts/build-scripts/build-all.js --continue-on-error

Library-Only Build

# Build only libraries
node tools/scripts/build-scripts/build-libs.js

# Build specific library
node tools/scripts/build-scripts/build-libs.js core-types

Application-Only Build

# Build all applications
node tools/scripts/build-scripts/build-apps.js

# Build specific application
node tools/scripts/build-scripts/build-apps.js docs-angular

Troubleshooting Builds

# Clean and rebuild with cache skip
node tools/scripts/build-scripts/clean-dist.js
node tools/scripts/build-scripts/build-all.js --skip-nx-cache

# Use fallback copy method for problematic library
node tools/scripts/build-scripts/copy-lib.js theme-system

🐛 Common Build Issues

1. "Cannot destructure property 'pos'" Error

Solution: The scripts automatically patch TypeScript to prevent this error.

2. Project Graph Issues

Solution: Use manual strategy or copy method:

node tools/scripts/build-scripts/build-apps.js --strategy=manual
node tools/scripts/build-scripts/copy-lib.js <library-name>

3. Cache Corruption

Solution: Clean and rebuild with cache skip:

node tools/scripts/build-scripts/clean-dist.js
node tools/scripts/build-scripts/build-all.js --skip-nx-cache

4. Theme System Build Failures

Solution: The scripts automatically fix common theme errors and use copy method as fallback.

📊 Build Monitoring

Check Build Status

# Check if critical libraries are built
ls -la dist/libs/

# Check specific library
ls -la dist/libs/core-types/

Build Reports

The scripts provide detailed build reports including:

• Success/failure status for each target
• Build time information
• Error details and recovery actions
• Cache usage statistics

🔄 Continuous Integration

CI/CD Integration

# Production build for CI
node tools/scripts/build-scripts/build-all.js --skip-nx-cache

# Development build for testing
node tools/scripts/build-scripts/build-all.js --dev --continue-on-error

Docker Integration

# Use alternative cache directory in containers
NX_CACHE_DIRECTORY=/tmp/nx-cache node tools/scripts/build-scripts/build-all.js

📝 Best Practices

1. Always clean before major builds:

   node tools/scripts/build-scripts/clean-dist.js
   

2. Use continue-on-error for development:

   node tools/scripts/build-scripts/build-all.js --continue-on-error
   

3. Skip cache when troubleshooting:

   node tools/scripts/build-scripts/build-all.js --skip-nx-cache
   

4. Build libraries before applications:

   node tools/scripts/build-scripts/build-libs.js
   node tools/scripts/build-scripts/build-apps.js
   

5. Use specific targets for faster builds:

   node tools/scripts/build-scripts/build-libs.js core-types
   

🤝 Contributing

To improve build scripts:

1. Test with different build scenarios
2. Add new fallback strategies as needed
3. Update library build order when dependencies change
4. Add new problematic library handling
5. Improve error reporting and recovery

📄 License

These scripts are part of the project and follow the same license terms.