Convention: How should Angular barrel imports be handled in framework-ag...

Documentation for Sessions

📏 Convention: How should Angular barrel imports be handled in framework-ag...

Date: 2026-03-23
Time: 17:02:50 UTC
Session: gspace1-258.6
Agent: angular
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should Angular barrel imports be handled in framework-agnostic libraries?

Task: S258: Convention for framework-agnostic library imports

🎯 Decision Made

Chosen:

Framework-agnostic libraries must NEVER import from Angular library barrels, even if the specific type needed is pure TypeScript. Barrel imports transitively pull the entire module graph including Angular services/decorators. Instead: (1) Import types from @libs-foundational/core-models (verified pure TS). (2) Define lightweight local types for shapes needed from Angular barrels (PluginDropPayload instead of DragPayload, CHAT_MODEL_IDS instead of AI_MODELS_CONFIG). (3) Define provider interfaces that Angular services implement.

Options Considered:

Import from barrels and hope tree-shaking removes Angular (doesn't work — type imports still resolve the module graph)
Use deep path imports like @libs-ux/embeddable-bridge/src/lib/models/... (fragile, breaks on refactor)
Define local lightweight types + provider interfaces (chosen — clean dependency boundary)

💭 Reasoning

Three Angular barrel contamination vectors discovered during S258: (A) @libs-ux/embeddable-bridge — DragPayload is pure TS but barrel re-exports Angular directives/services. (B) @libs-foundational/api-config — AI_MODELS_CONFIG is pure TS but barrel re-exports InjectionToken from @angular/core. (C) @libs-ai/vitto-core — VittoPageContextRegistry is an @Injectable Angular service. All three would have broken the zero-Angular-deps guarantee of chat-plugin-core. This is a systemic pattern: most NX library barrels mix pure TS types with Angular constructs. Any framework-agnostic library must verify each dependency's barrel before importing.

📁 Files Involved

libs/libs-ai/chat-plugin-core/src/lib/types/chat-core.types.ts
libs/libs-ai/chat-plugin-core/src/lib/interfaces/plugin-providers.interface.ts
libs/libs-ai/chat-plugin-core/src/lib/types/model-constants.ts

🔗 Related

Decision ID: dev_1774285370109_89fuihs
Session: 258
Workspace: gspace1

Auto-generated by MCP Smart Consolidation