🚨 Build System Known Issues & Solutions

🎉 NEW: Automated Build System (October 2024)

We now have a unified, automated build system that handles most issues automatically!

Quick Start with New System

# Build everything (one command!)
node build.js

# Generate new library with auto-configuration
node generate-lib.js my-awesome-lib

Benefits:

• ✅ Handles TypeScript 5.8.x + ng-packagr issues automatically
• ✅ Cross-platform (Mac, Windows, Linux)
• ✅ Intelligent dependency resolution
• ✅ No manual path configuration needed
• ✅ Self-healing for common errors

Documentation:

• 📖 Full documentation: tools/automation/README.md
• 📖 Migration guide: tools/scripts/build-scripts/README.md

Critical Issue: TypeScript 5.8.x + ng-packagr Incompatibility

Last Updated: October 17, 2024
Status: 🟢 AUTOMATED SOLUTION - Handled by Build System
Impact: HIGH - Blocks Angular library builds (but now automated)

The Problem

Error Signature

Cannot destructure property 'pos' of 'file.referencedFiles[index]' as it is undefined.

TypeError: Cannot destructure property 'pos' of 'file.referencedFiles[index]' as it is undefined.
    at getReferencedFileLocation
    at fileIncludeReasonToDiagnostics

Root Cause

• TypeScript 5.8.x has breaking changes in internal APIs
• ng-packagr 20.x uses these internal APIs for building Angular libraries
• The combination causes build failures for ANY Angular library using @nx/angular:ng-packagr-lite executor

Why This Happens

1. ng-packagr tries to analyze TypeScript files
2. TypeScript 5.8.x changed internal structures for file references
3. ng-packagr 20.x expects the old structure
4. Build crashes with the destructuring error above

Why We Can't Just Update

• ng-packagr 21.x (which might fix this) requires Node 18/20/22
• Our project uses Node 24.7.0
• [email protected] dependency blocks the upgrade
• We are stuck between incompatible versions

The Solution: Custom Build Script

Overview

We use a custom Angular library build script at tools/scripts/build-angular-library.js that:

• ✅ Bypasses ng-packagr completely
• ✅ Uses TypeScript compiler directly
• ✅ Generates proper Angular metadata
• ✅ Works with TypeScript 5.8.x
• ✅ Outputs ONLY to dist/, never to source directories

Libraries Using Custom Build Script

1. gograb-ai - Uses custom script (✅ WORKING)
2. ux-ui-core - Uses custom script (✅ WORKING)
3. ux-top-nav - Uses custom script (✅ WORKING)
4. ux-menu - Uses custom script (✅ WORKING)
5. storage-system - Uses @nx/js:tsc (✅ WORKING - TypeScript only, not Angular-specific)

How to Apply the Workaround

Step 1: Update project.json

Replace the ng-packagr executor with the custom script:

{
  "targets": {
    "build": {
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/libs/YOUR-LIBRARY"],
      "options": {
        "command": "node tools/scripts/build-angular-library.js YOUR-LIBRARY"
      },
      "configurations": {
        "production": {
          "command": "node tools/scripts/build-angular-library.js YOUR-LIBRARY"
        },
        "development": {
          "command": "node tools/scripts/build-angular-library.js YOUR-LIBRARY"
        }
      },
      "defaultConfiguration": "production",
      "parallelism": true,
      "cache": true
    }
  }
}

Step 2: Update tsconfig.lib.json

Critical configuration to prevent source directory pollution:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "baseUrl": ".",
    "outDir": "../../dist/libs/YOUR-LIBRARY",
    "rootDir": "./src",  // ⚠️ CRITICAL: Forces all output to respect source structure
    "declaration": true,
    "declarationMap": false,
    "sourceMap": false,
    "types": ["node"],
    "moduleResolution": "node",
    "module": "commonjs",
    "target": "es2016",
    "composite": false,  // ⚠️ CRITICAL: Prevents TS project reference issues
    "lib": ["es2016", "dom"],
    "skipLibCheck": true,
    "paths": {
      // Reference OTHER libraries from their BUILT output, not source
      "@other-lib": ["../../dist/libs/other-lib/src"]
    }
  },
  "exclude": ["src/**/*.spec.ts", "src/test-setup.ts", "jest.config.ts", "src/**/*.test.ts"],
  "include": ["src/**/*.ts"]
}

Step 3: Add Peer Dependencies

If your library depends on other internal libraries, add them as peer dependencies in package.json:

{
  "peerDependencies": {
    "@angular/core": "^20.0.0",
    "@angular/common": "^20.0.0",
    "@storage-system": "*",
    "@other-internal-lib": "*"
  }
}

Step 4: Clean Up Generated Files

Run the cleanup script to remove any .js, .d.ts, .js.map files from source directories:

bash scripts/cleanup-generated-files.sh

These files should ONLY exist in dist/, NEVER in libs/ source directories.

Preventing Generated Files in Source

Why This Happens

• TypeScript's composite: true can cause output in source directories
• Wrong rootDir or outDir configuration
• Multiple tsconfig files with conflicting settings

The Fix

1. Always set rootDir: "./src" in tsconfig.lib.json
2. Always set composite: false (unless you need project references)
3. Always set outDir: "../../dist/libs/YOUR-LIBRARY"
4. Run cleanup script after any build issues

Automated Cleanup

The script at scripts/cleanup-generated-files.sh intelligently removes:

• *.js files ONLY if a corresponding .ts source file exists (i.e., it was generated)
• *.js.map files ONLY if a corresponding .ts source file exists
• *.d.ts files ONLY if a corresponding .ts source file exists
• *.d.ts.map files ONLY if a corresponding .ts source file exists

Preserved: Standalone .js files (config files, scripts without .ts sources)
Cleaned: Generated compilation outputs from TypeScript files
Directories: Only scans libs/ and apps/, excludes dist/ and node_modules/

Common Pitfalls

❌ DON'T: Use ng-packagr with TypeScript 5.8.x

// This WILL FAIL:
{
  "executor": "@nx/angular:ng-packagr-lite"
}

❌ DON'T: Reference source files from tsconfig paths

// This causes circular dependencies and build issues:
{
  "paths": {
    "@storage-system": ["../../libs/storage-system/src/index.ts"]  // WRONG
  }
}

❌ DON'T: Use composite: true without understanding it

// This can generate files in source directories:
{
  "composite": true  // AVOID unless you need TS project references
}

✅ DO: Use custom build script

{
  "executor": "nx:run-commands",
  "options": {
    "command": "node tools/scripts/build-angular-library.js YOUR-LIBRARY"
  }
}

✅ DO: Reference built output

{
  "paths": {
    "@storage-system": ["../../dist/libs/storage-system/src"]  // CORRECT
  }
}

✅ DO: Set rootDir explicitly

{
  "rootDir": "./src",  // Forces proper output structure
  "composite": false
}

Debugging Build Issues

Check 1: Are files being generated in source?

find libs/ apps/ -name "*.js" -o -name "*.d.ts" | grep -v node_modules | grep -v dist

Expected: NO results (or only intentional .js config files)
If you see files: Run bash scripts/cleanup-generated-files.sh

Check 2: Is the library using the right executor?

cat libs/YOUR-LIBRARY/project.json | grep -A 3 "build"

Expected: "executor": "nx:run-commands" with custom script
If ng-packagr: Switch to custom build script (see above)

Check 3: Are paths pointing to built output?

cat libs/YOUR-LIBRARY/tsconfig.lib.json | grep -A 5 "paths"

Expected: Paths like ../../dist/libs/OTHER-LIB/src
If pointing to libs/: Change to dist/ paths

Check 4: Is TypeScript configured correctly?

cat libs/YOUR-LIBRARY/tsconfig.lib.json | grep -E "(rootDir|outDir|composite)"

Expected:

• "rootDir": "./src"
• "outDir": "../../dist/libs/YOUR-LIBRARY"
• "composite": false

Testing the Fix

Full Clean Build Test

# 1. Clean everything
rm -rf dist/ .angular/

# 2. Clean source directories
bash scripts/cleanup-generated-files.sh

# 3. Build the library
yarn nx build YOUR-LIBRARY --skip-nx-cache

# 4. Verify no source pollution
find libs/YOUR-LIBRARY/src -name "*.js" -o -name "*.d.ts"
# Should return NOTHING (or only intentional config files)

# 5. Verify dist exists
ls -la dist/libs/YOUR-LIBRARY/src/*.d.ts
# Should show compiled output

When This Bug Will Be Fixed

Upstream Fix Required

1. ng-packagr needs to update for TypeScript 5.8.x compatibility
2. OR TypeScript needs to maintain backward-compatible internal APIs
3. OR Our project needs to downgrade Node.js to 18/20/22 for ng-packagr 21.x

Current Status (Oct 2024)

• ng-packagr 21.x exists but we can't use it (Node version conflict)
• TypeScript 5.8.x is required by Angular 20
• No timeline for fix - workaround is permanent for now

Related Files

Configuration Files

• tools/scripts/build-angular-library.js - Custom build script
• scripts/cleanup-generated-files.sh - Source directory cleanup
• tsconfig.base.json - Global TypeScript config
• tsconfig.json - Root TypeScript config

Example Configurations

• libs/gograb-ai/project.json - Custom script setup
• libs/gograb-ai/tsconfig.lib.json - Proper TypeScript config
• libs/ux-top-nav/project.json - Custom script setup
• libs/storage-system/project.json - Plain TypeScript build

Quick Reference Commands

# Clean source directories
bash scripts/cleanup-generated-files.sh

# Build single library
yarn nx build YOUR-LIBRARY --skip-nx-cache

# Build with dependencies
yarn nx build YOUR-LIBRARY --with-deps

# Check for source pollution
find libs/ apps/ -name "*.js" -o -name "*.d.ts" | grep -v node_modules | grep -v dist | wc -l

# Full rebuild from scratch
rm -rf dist/ .angular/ && yarn nx build YOUR-LIBRARY

Emergency Recovery

If builds are completely broken:

# 1. Nuclear option - clean everything
rm -rf dist/ .angular/ node_modules/.cache

# 2. Clean source directories
bash scripts/cleanup-generated-files.sh

# 3. Rebuild storage-system first (other libs depend on it)
yarn nx build storage-system --skip-nx-cache

# 4. Rebuild your library
yarn nx build YOUR-LIBRARY --skip-nx-cache

# 5. If still failing, check tsconfig paths point to dist/
cat libs/YOUR-LIBRARY/tsconfig.lib.json

🚀 The New Automated System

What Changed

We've built a comprehensive automation system that eliminates manual configuration and handles build issues automatically.

Key Components

1. Unified Build System (tools/automation/build/unified-build.js)

   • Analyzes entire workspace structure
   • Builds dependency graph automatically
   • Handles all build strategies
   • Uses custom Angular builder when needed
   • Cross-platform compatible

2. Library Generator (tools/automation/generators/generate-library.js)

   • Interactive library creation
   • Auto-configures all settings
   • Sets up common dependencies
   • Creates proper structure
   • Zero manual configuration

3. Path Resolver (tools/automation/core/path-resolver.js)

   • Scans workspace for libraries
   • Generates path mappings
   • Updates tsconfig automatically
   • Handles nested libraries

4. Platform Utils (tools/automation/core/platform-utils.js)

   • Cross-platform command execution
   • File operations
   • Terminal output formatting
   • Works on Mac, Windows, Linux

How It Solves Our Problems

Migration

All old scripts in tools/scripts/build-scripts/ are now deprecated.

Use instead:

# Old way
bash tools/scripts/build-scripts/build-nx.sh
node tools/scripts/build-scripts/build-libs.js
node tools/scripts/build-scripts/fix-build-issues.js

# New way (one command)
node build.js

See tools/scripts/build-scripts/README.md for full migration guide.

History

✨ NEW PARADIGM: The build system is now fully automated. Focus on writing code, not fighting with builds!

⚠️ REMEMBER: This is NOT a configuration issue - it's a KNOWN BUG in the tooling. The workaround (custom build script) is necessary and correct, but now handled automatically.