// src/app/services/chart-engine.service.ts
import { Injectable } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class ChartEngineService {
  private readonly engine: any;

  constructor() {
    // Simulating heavy library initialization (e.g., echarts, d3, chart.js)
    this.engine = null; 
  }

  async initialize(): Promise<void> {
    const lib = await import('echarts');
    this.engine = lib.init;
  }

  render(container: HTMLElement, config: Record<string, unknown>): void {
    if (!this.engine) throw new Error('Chart engine not initialized');
    const instance = this.engine(container);
    instance.setOption(config);
  }
}

// src/app/components/metrics-panel.component.ts
import { Component, injectAsync, signal, DestroyRef, inject } from '@angular/core';
import { ChartEngineService } from '../services/chart-engine.service';

@Component({
  selector: 'app-metrics-panel',
  standalone: true,
  template: `
    <div class="panel-header">
      <h2>Real-Time Metrics</h2>
      @if (isLoading()) {
        <span class="loader">Initializing visualization...</span>
      }
    </div>
    <div #chartContainer class="chart-area"></div>
  `
})
export class MetricsPanelComponent {
  protected readonly isLoading = signal(false);
  protected readonly chartContainer = signal<HTMLElement | null>(null);
  
  private readonly destroyRef = inject(DestroyRef);
  
  // Declarative lazy loading with framework-managed caching
  private readonly chartLoader = injectAsync(
    () => import('../services/chart

-engine.service').then(m => m.ChartEngineService) );

async mountVisualization(): Promise<void> { this.isLoading.set(true); try { const ChartClass = await this.chartLoader(); const engine = new ChartClass(); await engine.initialize();

  const container = this.chartContainer();
  if (container) {
    engine.render(container, {
      xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
      yAxis: { type: 'value' },
      series: [{ data: [120, 200, 150], type: 'line' }]
    });
  }
} catch (error) {
  console.error('Failed to load chart engine:', error);
} finally {
  this.isLoading.set(false);
}

} }

### Step 3: Configure Background Prefetching
Angular v22 allows you to trigger the dynamic import before the user explicitly requests the feature. This eliminates perceived latency without blocking the initial render.

```typescript
import { injectAsync, onIdle } from '@angular/core';

// ... inside component class
private readonly chartLoader = injectAsync(
  () => import('../services/chart-engine.service').then(m => m.ChartEngineService),
  { prefetch: onIdle }
);

Architecture Decisions & Rationale

• Loader Function Pattern: injectAsync() accepts a function, not a promise directly. This defers the import() call until the first invocation or prefetch trigger, preventing premature network requests.
• Automatic Caching: The framework stores the resolved promise. Subsequent calls to await this.chartLoader() return the cached instance immediately, avoiding redundant dynamic imports.
• Signal-Driven UI State: Using signal() for loading states ensures Angular’s change detection only updates the DOM when the async operation transitions, preventing unnecessary render cycles.
• Prefetch Strategy: onIdle leverages the browser’s idle periods to fetch the chunk. This is superior to eager loading because it respects the critical rendering path, and superior to pure on-demand loading because it masks network latency.

Pitfall Guide

1. Awaiting Outside Execution Context

Explanation: Calling await this.chartLoader() during component property initialization or inside a synchronous lifecycle hook (ngOnInit) breaks the injection context and throws runtime errors. Fix: Always invoke the async loader inside an async method, event handler, or effect. Never await it during class instantiation.

2. Ignoring SSR/SSG Compatibility

Explanation: Dynamic imports and browser-only APIs fail during server-side rendering. Angular will throw a ReferenceError when attempting to resolve the chunk in a Node environment. Fix: Guard the loader with isPlatformBrowser() or conditionally render the component only on the client. Use inject(PLATFORM_ID) to branch logic safely.

3. Recreating Loader Functions in Loops

Explanation: If you pass a newly constructed function to injectAsync() on every change detection cycle, the framework may treat it as a distinct loader, bypassing internal caching and triggering multiple network requests. Fix: Define the loader function as a class property or use useMemo-style patterns. Ensure the reference remains stable across renders.

4. Forgetting Error Boundaries

Explanation: Network failures, chunk corruption, or missing files will cause the promise to reject. Without explicit handling, the component enters an undefined state. Fix: Wrap await this.chartLoader() in try/catch. Bind errors to a signal and display fallback UI. Consider implementing retry logic with exponential backoff for flaky networks.

5. Over-Deferring Critical Path Services

Explanation: Applying injectAsync() to services required for initial paint (e.g., authentication resolvers, routing guards, or layout calculators) introduces artificial latency. Fix: Profile your application first. Only defer services that are triggered by user interaction, secondary tabs, or non-visible features. Use Lighthouse or WebPageTest to validate FCP impact.

6. Race Conditions in Rapid UI Toggles

Explanation: If a user rapidly opens and closes a panel that triggers the loader, multiple promises may resolve out of order, causing stale data to render or memory leaks. Fix: Implement a cancellation token or check a isMounted flag before applying results. Alternatively, debounce the trigger event and ensure only the latest request updates the DOM.

7. Misunderstanding Prefetch Timing

Explanation: onIdle does not guarantee immediate loading. On low-end devices or heavy pages, the browser may never reach an idle state, leaving the chunk unloaded. Fix: Pair prefetch: onIdle with a fallback on-demand trigger. If the user interacts with the feature before idle fires, the loader will fetch synchronously, ensuring functionality remains intact.

Production Bundle

Action Checklist

• Audit third-party dependencies: Identify libraries exceeding 20kb that are not required for initial render.
• Replace inject(Service) with injectAsync() loader functions in consuming components.
• Wrap all await calls in try/catch blocks and bind errors to UI state signals.
• Add prefetch: onIdle to services triggered by secondary interactions (tabs, modals, tooltips).
• Verify SSR compatibility by guarding dynamic imports with isPlatformBrowser().
• Run bundle analysis (ng build --stats-json) to confirm chunk separation and size reduction.
• Implement loading spinners or skeleton UI to mask network latency during on-demand resolution.
• Test on throttled networks (3G/4G) to validate prefetch effectiveness and fallback behavior.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Service required for initial paint (auth, routing, layout)	Eager inject()	Deferring introduces unacceptable latency and breaks critical path	Higher initial bundle, faster TTI
Service triggered by user action (modals, exports, charts)	injectAsync() with prefetch: onIdle	Masks network latency without blocking render	Lower initial bundle, negligible runtime cost
Service used in SSR/SSG context	Eager inject() + platform guard	Dynamic imports fail in Node; SSR requires synchronous resolution	Server payload increases, but stability improves
Feature toggled rapidly (tabs, accordions)	injectAsync() + signal-based state management	Prevents race conditions and redundant network requests	Slightly higher memory usage, cleaner UX
Heavy library with multiple entry points	Split into micro-services + injectAsync()	Enables granular chunking and independent caching	Optimized network payload, complex DI setup

Configuration Template

Copy this structure into your project to standardize deferred service resolution across teams.

// src/app/core/decorators/deferred-service.ts
import { injectAsync, onIdle, OnIdle } from '@angular/core';

export type PrefetchStrategy = 'none' | 'onIdle' | 'onInteraction';

export function createDeferredLoader<T>(
  importFn: () => Promise<{ default: T } | T>,
  strategy: PrefetchStrategy = 'none'
) {
  const prefetchConfig = strategy === 'onIdle' ? { prefetch: onIdle } : undefined;
  
  return injectAsync(
    () => importFn().then(mod => mod.default || mod),
    prefetchConfig
  );
}

// Usage in component:
// private readonly heavyService = createDeferredLoader(
//   () => import('../services/heavy.service'),
//   'onIdle'
// );

Quick Start Guide

1. Identify Target: Locate a component that imports a heavy utility library not needed during initial render.
2. Extract Service: Ensure the library is wrapped in an @Injectable() service class.
3. Swap Injection: Replace inject(HeavyService) with injectAsync(() => import('./heavy.service').then(m => m.HeavyService)).
4. Handle Async: Convert the consuming method to async, await the loader, and bind loading/error states to signals.
5. Validate: Run ng build --configuration production, inspect the generated chunks, and verify FCP improvement using Chrome DevTools Performance tab.