feat: hmr with compiled components and route preservation

Author: NathanWalker

packages/angular/src/lib/application.ts

@@ -1,5 +1,6 @@
 import * as AngularCore from '@angular/core';
 import { ApplicationRef, EnvironmentProviders, NgModuleRef, NgZone, PlatformRef, Provider } from '@angular/core';
+import { Router } from '@angular/router';
 import {
   Application,
   ApplicationEventData,
@@ -15,7 +16,9 @@ import {
 import { Observable, Subject } from 'rxjs';
 import { filter, map, take } from 'rxjs/operators';
 import { AppHostView } from './app-host-view';
+import { resetAngularHmrCompiledComponents } from './hmr-compiled-components-core';
 import { NativeScriptLoadingService } from './loading.service';
+import { clearAngularHmrRouteConfigCaches } from './legacy/router/hmr-route-cache-core';
 import { APP_ROOT_VIEW, DISABLE_ROOT_VIEW_HANDLING, NATIVESCRIPT_ROOT_MODULE_ID } from './tokens';
 import { NativeScriptDebug } from './trace';
 
@@ -230,6 +233,17 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
   let loadingModuleRef: NgModuleRef<K> | ApplicationRef;
   let platformRef: PlatformRef = null;
   let bootstrapId = -1;
+  const clearAngularHmrRouteCaches = () => {
+    try {
+      const injector = (mainModuleRef as any)?.injector;
+      const router = injector?.get?.(Router, null);
+      const cleared = clearAngularHmrRouteConfigCaches(router?.config);
+
+      if (cleared > 0) {
+        console.log('[ng-hmr] cleared Angular route caches before reboot:', cleared);
+      }
+    } catch {}
+  };
   const updatePlatformRef = (moduleRef: NgModuleRef<T | K> | ApplicationRef, reason: NgModuleReason) => {
     const newPlatformRef = moduleRef.injector.get(PlatformRef);
     if (newPlatformRef === platformRef) {
@@ -555,12 +569,20 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
     platformRef = null;
   };
   const disposeLastModules = (reason: NgModuleReason) => {
+    if (reason === 'hotreload') {
+      clearAngularHmrRouteCaches();
+    }
+
     // reset bootstrap ID to make sure any modules bootstrapped after this are discarded
     bootstrapId = -1;
     destroyRef(loadingModuleRef, 'loading', reason);
     loadingModuleRef = null;
     destroyRef(mainModuleRef, 'main', reason);
     mainModuleRef = null;
+
+    if (reason === 'hotreload') {
+      resetAngularHmrCompiledComponents(AngularCore as any);
+    }
   };
   const launchCallback = profile('@nativescript/angular/platform-common.launchCallback', (args: LaunchEventData) => {
     launchEventDone = false;
@@ -615,6 +637,9 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
   global['__reboot_ng_modules__'] = (shouldDisposePlatform: boolean = false) => {
     console.log('[ng-hmr] __reboot_ng_modules__ called, shouldDisposePlatform:', shouldDisposePlatform);
     console.log('[ng-hmr] current bootstrapId:', bootstrapId, 'mainModuleRef:', !!mainModuleRef);
+    try {
+      global['__NS_CAPTURE_ANGULAR_HMR_ROUTE__']?.();
+    } catch {}
     disposeLastModules('hotreload');
     console.log('[ng-hmr] after disposeLastModules, bootstrapId:', bootstrapId);
     if (shouldDisposePlatform) {

packages/angular/src/lib/hmr-compiled-components-core.spec.ts

@@ -0,0 +1,27 @@
+import { resetAngularHmrCompiledComponents } from './hmr-compiled-components-core';
+
+describe('Angular HMR compiled component reset', () => {
+  it('calls Angular internal compiled-component reset when available', () => {
+    const core = {
+      ɵresetCompiledComponents: jest.fn(),
+    };
+
+    expect(resetAngularHmrCompiledComponents(core)).toBe(true);
+    expect(core.ɵresetCompiledComponents).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns false when Angular core does not expose the reset hook', () => {
+    expect(resetAngularHmrCompiledComponents({})).toBe(false);
+  });
+
+  it('swallows reset failures so HMR disposal can continue', () => {
+    const core = {
+      ɵresetCompiledComponents: jest.fn(() => {
+        throw new Error('boom');
+      }),
+    };
+
+    expect(resetAngularHmrCompiledComponents(core)).toBe(false);
+    expect(core.ɵresetCompiledComponents).toHaveBeenCalledTimes(1);
+  });
+});

packages/angular/src/lib/hmr-compiled-components-core.ts

@@ -0,0 +1,19 @@
+type AngularCoreWithCompiledComponentReset = {
+  ɵresetCompiledComponents?: () => void;
+};
+
+export function resetAngularHmrCompiledComponents(
+  core: AngularCoreWithCompiledComponentReset | null | undefined,
+): boolean {
+  const resetCompiledComponents = core?.ɵresetCompiledComponents;
+  if (typeof resetCompiledComponents !== 'function') {
+    return false;
+  }
+
+  try {
+    resetCompiledComponents.call(core);
+    return true;
+  } catch {
+    return false;
+  }
+}

packages/angular/src/lib/legacy/router/hmr-route-cache-core.ts

@@ -0,0 +1,61 @@
+type AngularHmrRouteLike = {
+  children?: AngularHmrRouteLike[];
+  _injector?: unknown;
+  _loadedComponent?: unknown;
+  _loadedInjector?: unknown;
+  _loadedRoutes?: AngularHmrRouteLike[];
+};
+
+const ROUTE_CACHE_KEYS = ['_loadedComponent', '_loadedInjector', '_loadedRoutes', '_injector'] as const;
+
+function clearRouteCacheField(route: Record<string, unknown>, key: (typeof ROUTE_CACHE_KEYS)[number]): boolean {
+  if (!Object.prototype.hasOwnProperty.call(route, key) && route[key] === undefined) {
+    return false;
+  }
+
+  try {
+    delete route[key];
+  } catch {
+    try {
+      route[key] = undefined;
+    } catch {}
+  }
+
+  return true;
+}
+
+export function clearAngularHmrRouteConfigCaches(routes: AngularHmrRouteLike[] | undefined | null): number {
+  const seen = new Set<AngularHmrRouteLike>();
+  let cleared = 0;
+
+  const visitRoute = (route: AngularHmrRouteLike | undefined | null): void => {
+    if (!route || seen.has(route)) {
+      return;
+    }
+
+    seen.add(route);
+
+    const childRoutes = Array.isArray(route.children) ? route.children : [];
+    const loadedRoutes = Array.isArray(route._loadedRoutes) ? route._loadedRoutes : [];
+
+    for (const childRoute of childRoutes) {
+      visitRoute(childRoute);
+    }
+
+    for (const loadedRoute of loadedRoutes) {
+      visitRoute(loadedRoute);
+    }
+
+    for (const key of ROUTE_CACHE_KEYS) {
+      if (clearRouteCacheField(route as Record<string, unknown>, key)) {
+        cleared += 1;
+      }
+    }
+  };
+
+  for (const route of Array.isArray(routes) ? routes : []) {
+    visitRoute(route);
+  }
+
+  return cleared;
+}

packages/angular/src/lib/legacy/router/hmr-route-cache.spec.ts

@@ -0,0 +1,69 @@
+import { clearAngularHmrRouteConfigCaches } from './hmr-route-cache-core';
+
+describe('Angular HMR route cache clearing', () => {
+  it('clears lazy route caches recursively while preserving public route fields', () => {
+    const grandchild = {
+      path: 'details',
+      _loadedComponent: { name: 'DetailsComponent' },
+      _loadedInjector: { token: 'details' },
+    };
+    const child = {
+      path: 'survey',
+      children: [grandchild],
+      _loadedComponent: { name: 'SurveyComponent' },
+      _loadedInjector: { token: 'survey' },
+      _injector: { token: 'child-injector' },
+    };
+    const route = {
+      path: 'onboarding-flow',
+      children: [child],
+      _loadedRoutes: [
+        {
+          path: 'lazy',
+          _loadedComponent: { name: 'LazyComponent' },
+          _loadedRoutes: [
+            {
+              path: 'nested',
+              _injector: { token: 'nested-injector' },
+            },
+          ],
+        },
+      ],
+    };
+
+    const cleared = clearAngularHmrRouteConfigCaches([route]);
+
+    expect(cleared).toBe(9);
+    expect(route.path).toBe('onboarding-flow');
+    expect(child.path).toBe('survey');
+    expect(grandchild.path).toBe('details');
+    expect((route as any)._loadedRoutes).toBeUndefined();
+    expect((child as any)._loadedComponent).toBeUndefined();
+    expect((child as any)._loadedInjector).toBeUndefined();
+    expect((child as any)._injector).toBeUndefined();
+    expect((grandchild as any)._loadedComponent).toBeUndefined();
+    expect((grandchild as any)._loadedInjector).toBeUndefined();
+  });
+
+  it('does not loop forever when route graphs reuse the same child object', () => {
+    const shared = {
+      path: 'shared',
+      _loadedComponent: { name: 'SharedComponent' },
+    };
+    const routes = [
+      {
+        path: 'a',
+        children: [shared],
+      },
+      {
+        path: 'b',
+        _loadedRoutes: [shared],
+      },
+    ];
+
+    const cleared = clearAngularHmrRouteConfigCaches(routes as any);
+
+    expect(cleared).toBe(2);
+    expect((shared as any)._loadedComponent).toBeUndefined();
+  });
+});

packages/angular/src/lib/legacy/router/hmr-route-state-core.ts

@@ -0,0 +1,95 @@
+type AngularHmrRouteState = {
+  url: string;
+  source: string;
+  timestamp: number;
+};
+
+const CURRENT_ROUTE_KEY = '__NS_ANGULAR_HMR_CURRENT_ROUTE__';
+const PENDING_START_PATH_KEY = '__NS_ANGULAR_HMR_PENDING_START_PATH__';
+const CAPTURE_ROUTE_KEY = '__NS_CAPTURE_ANGULAR_HMR_ROUTE__';
+
+function getGlobalState(): any {
+  return globalThis as any;
+}
+
+export function normalizeAngularHmrRouteUrl(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  if (trimmed.startsWith('/')) {
+    return trimmed;
+  }
+
+  if (trimmed.startsWith('?') || trimmed.startsWith('#')) {
+    return `/${trimmed}`;
+  }
+
+  return `/${trimmed.replace(/^\/+/, '')}`;
+}
+
+export function writeAngularHmrRouteState(
+  value: unknown,
+  options: {
+    pending?: boolean;
+    source: string;
+  },
+): string | null {
+  const url = normalizeAngularHmrRouteUrl(value);
+  if (!url) {
+    return null;
+  }
+
+  const state: AngularHmrRouteState = {
+    url,
+    source: options.source,
+    timestamp: Date.now(),
+  };
+
+  const g = getGlobalState();
+  g[CURRENT_ROUTE_KEY] = state;
+  if (options.pending) {
+    g[PENDING_START_PATH_KEY] = state;
+  }
+
+  return url;
+}
+
+export function captureAngularHmrPendingStartPath(value: unknown, source = 'hmr-reboot'): string | null {
+  return writeAngularHmrRouteState(value, { pending: true, source });
+}
+
+export function readAngularHmrPendingStartPath(): string {
+  const g = getGlobalState();
+  return normalizeAngularHmrRouteUrl(g[PENDING_START_PATH_KEY]?.url ?? g[PENDING_START_PATH_KEY]) || '';
+}
+
+export function invokeAngularHmrRouteCapture(): string | null {
+  const g = getGlobalState();
+  const capture = g[CAPTURE_ROUTE_KEY];
+  if (typeof capture === 'function') {
+    try {
+      return capture();
+    } catch {
+      // Fall back to the last known router url when the active capture hook fails.
+    }
+  }
+
+  return captureAngularHmrPendingStartPath(g[CURRENT_ROUTE_KEY]?.url ?? g[CURRENT_ROUTE_KEY], 'hmr-fallback');
+}
+
+export function installAngularHmrRouteCaptureHook(capture: () => string | null): () => void {
+  const g = getGlobalState();
+  g[CAPTURE_ROUTE_KEY] = capture;
+
+  return () => {
+    if (g[CAPTURE_ROUTE_KEY] === capture) {
+      delete g[CAPTURE_ROUTE_KEY];
+    }
+  };
+}