Architecture: How to successfully build Angular libraries in NX monorepo w...

Documentation for Sessions

🏗️ Architecture: How to successfully build Angular libraries in NX monorepo w...

Date: 2026-01-25
Time: 15:17:08 UTC
Session: editor2-70.4
Agent: angular
Confidence: 100%
Status: ✅ Documented

📋 Decision Context

Question:

How to successfully build Angular libraries in NX monorepo without ng-packagr TypeScript 5.8.x compatibility issues?

Task: Fix NX app gograb-space build issues

🎯 Decision Made

Chosen:

Use nx:run-commands with custom build script (build-angular-library.js)

Options Considered:

  1. Use @nx/angular:ng-packagr-lite executor
  2. Use nx:run-commands with custom build script
  3. Use direct tsc compilation
  4. Use @nx/angular:package executor

💭 Reasoning

The @nx/angular:ng-packagr-lite executor triggers a TypeScript 5.8.x compatibility issue ("Cannot destructure property 'pos'") during complex dependency graph processing. The custom build script (tools/scripts/build/build-angular-library.js) successfully bypasses this by:

  1. Direct TypeScript Compilation: Uses tsc directly without ng-packagr's complex file processing
  2. Isolated TSConfig: Creates a build-specific tsconfig that prevents source directory pollution
  3. Smart Path Remapping: Automatically remaps paths from libs/ to dist/libs/ handling both nested and flat structures
  4. Asset Management: Handles SCSS compilation, HTML templates, package.json, and metadata
  5. Output Reorganization: Flattens nested dist structures that TypeScript may create
  6. Source Protection: Cleans up any generated files that might appear in source directories

This approach is proven successful across 92+ libraries in the gograb-space build, with all tasks completing successfully. The build is faster, more transparent, and avoids the ng-packagr TypeScript compatibility issue entirely.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation