🏗️ Architecture: How should Angular components be compiled and bundled for us...

Date: 2026-03-26
Time: 15:29:00 UTC
Session: gspace1-271.5
Agent: angular
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should Angular components be compiled and bundled for use as Custom Elements alongside Lit-based Platform Elements?

Task: Not specified

🎯 Decision Made

Chosen:

esbuild with @angular/* externalized via import maps. Self-hosted Angular runtime at /angular-runtime/ provides singleton guarantees. JIT compiler loaded as prerequisite before widget bundle. Lazy-loaded only when pe-* elements detected in DOM via MutationObserver.

Options Considered:

1. ngc pre-compilation + esbuild (complex build pipeline, no JIT needed)
2. esbuild with externals + JIT at runtime (chosen — simplest, proven)
3. Bundle Angular runtime INTO pe-angular-widgets.js (80KB+ larger, no singleton)

💭 Reasoning

Angular components use @Component decorators that need JIT compilation at runtime. Since the self-hosted Angular runtime (S264) already includes the JIT compiler, we compile TypeScript with esbuild (preserving decorator metadata) and externalize all @angular/* packages. The browser resolves them via import maps to singleton /angular-runtime/ bundles. The load chain MUST be: zone.js → @angular/compiler → pe-angular-widgets.js. Without compiler loaded first, @Component decorators fail silently. The lazy loader (MutationObserver on platform-app) ensures pages without pe-* elements never load Angular runtime — zero overhead for pure Lit pages.

📁 Files Involved

• tools/scripts/build/bundle-platform-elements-angular.ts
• tools/scripts/build/bundle-angular-runtime.ts
• libs/libs-structural/platform-elements/src/lib/runtime/angular-loader.ts
• libs/libs-structural/platform-preview/src/lib/config/esm-cdn-map.ts

🔗 Related

• Decision ID: dev_1774538940876_jc0jb6i
• Session: 271
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation