refactor(core): produce a message about @defer behavior when HMR is enabled

When the HMR is enabled in Angular, all `@defer` block dependencies are loaded
eagerly, instead of waiting for configured trigger conditions. From the DX perspective,
it might be seen as an issue when all dependencies are being loaded eagerly. This commit
adds a logic to produce a message into the console to provide more info for developers.

Author: AndrewKushnir

adev/src/content/reference/errors/NG0751.md

@@ -0,0 +1,13 @@
+# @defer behavior when HMR is enabled
+
+Hot Module Replacement (HMR) is a technique used by development servers to avoid reloading the entire page when only part of an application is changed.
+
+When the HMR is enabled in Angular, all `@defer` block dependencies are loaded
+eagerly, instead of waiting for configured trigger conditions (both for client-only and incremental hydration triggers). This is needed
+for the HMR to function properly, replacing components in an application at runtime
+without the need to reload the entire page. Note: the actual rendering of defer
+blocks respects trigger conditions in the HMR mode.
+
+If you want to test `@defer` block behavior in development mode and ensure that
+the necessary dependencies are loaded when a triggering condition is met, you can
+disable the HMR mode as described in [`this document`](/tools/cli/build-system-migration#hot-module-replacement).

goldens/public-api/core/errors.api.md

@@ -7,6 +7,9 @@
 // @public
 export function formatRuntimeError<T extends number = RuntimeErrorCode>(code: T, message: null | false | string): string;
 
+// @public (undocumented)
+export function formatRuntimeErrorCode<T extends number = RuntimeErrorCode>(code: T): string;
+
 // @public
 export class RuntimeError<T extends number = RuntimeErrorCode> extends Error {
     constructor(code: T, message: null | false | string);
@@ -29,6 +32,8 @@ export const enum RuntimeErrorCode {
     // (undocumented)
     CYCLIC_DI_DEPENDENCY = -200,
     // (undocumented)
+    DEFER_IN_HMR_MODE = -751,
+    // (undocumented)
     DEFER_LOADING_FAILED = -750,
     // (undocumented)
     DUPLICATE_DIRECTIVE = 309,

packages/core/src/application/application_ref.ts

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import '../util/ng_hmr_mode';
 import '../util/ng_jit_mode';
 import '../util/ng_server_mode';
 

packages/core/src/defer/instructions.ts

@@ -65,6 +65,35 @@ import {
   triggerResourceLoading,
   shouldAttachTrigger,
 } from './triggering';
+import {formatRuntimeError, RuntimeErrorCode} from '../errors';
+import {Console} from '../console';
+import {Injector} from '../di';
+
+/**
+ * Indicates whether we've already produced a warning,
+ * prevents the logic from producing it multiple times.
+ */
+let _hmrWarningProduced = false;
+
+/**
+ * Logs a message into the console to indicate that `@defer` block
+ * dependencies are loaded eagerly when the HMR mode is enabled.
+ */
+function logHmrWarning(injector: Injector) {
+  if (!_hmrWarningProduced) {
+    _hmrWarningProduced = true;
+    const console = injector.get(Console);
+    // tslint:disable-next-line:no-console
+    console.log(
+      formatRuntimeError(
+        RuntimeErrorCode.DEFER_IN_HMR_MODE,
+        'Angular has detected that this application contains `@defer` blocks ' +
+          'and the hot module replacement (HMR) mode is enabled. All `@defer` ' +
+          'block dependencies will be loaded eagerly.',
+      ),
+    );
+  }
+}
 
 /**
  * Creates runtime data structures for defer blocks.
@@ -108,6 +137,10 @@ export function ɵɵdefer(
   if (tView.firstCreatePass) {
     performanceMarkFeature('NgDefer');
 
+    if (ngDevMode && typeof ngHmrMode !== 'undefined' && ngHmrMode) {
+      logHmrWarning(injector);
+    }
+
     const tDetails: TDeferBlockDetails = {
       primaryTmplIndex,
       loadingTmplIndex: loadingTmplIndex ?? null,

packages/core/src/errors.ts

@@ -101,6 +101,7 @@ export const enum RuntimeErrorCode {
 
   // Defer errors (750-799 range)
   DEFER_LOADING_FAILED = -750,
+  DEFER_IN_HMR_MODE = -751,
 
   // standalone errors
   IMPORT_PROVIDERS_FROM_STANDALONE = 800,
@@ -169,6 +170,13 @@ export class RuntimeError<T extends number = RuntimeErrorCode> extends Error {
   }
 }
 
+export function formatRuntimeErrorCode<T extends number = RuntimeErrorCode>(code: T): string {
+  // Error code might be a negative number, which is a special marker that instructs the logic to
+  // generate a link to the error details page on angular.io.
+  // We also prepend `0` to non-compile-time errors.
+  return `NG0${Math.abs(code)}`;
+}
+
 /**
  * Called to format a runtime error.
  * See additional info on the `message` argument type in the `RuntimeError` class description.
@@ -177,10 +185,7 @@ export function formatRuntimeError<T extends number = RuntimeErrorCode>(
   code: T,
   message: null | false | string,
 ): string {
-  // Error code might be a negative number, which is a special marker that instructs the logic to
-  // generate a link to the error details page on angular.io.
-  // We also prepend `0` to non-compile-time errors.
-  const fullCode = `NG0${Math.abs(code)}`;
+  const fullCode = formatRuntimeErrorCode(code);
 
   let errorMessage = `${fullCode}${message ? ': ' + message : ''}`;
 

packages/core/src/util/ng_hmr_mode.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+declare global {
+  /**
+   * Indicates whether HMR is enabled for the application.
+   *
+   * `ngHmrMode` is a global flag set by Angular's CLI.
+   *
+   * @remarks
+   * - **Internal Angular Flag**: This is an *internal* Angular flag (not a public API), avoid relying on it in application code.
+   * - **Avoid Direct Use**: This variable is intended for runtime configuration; it should not be accessed directly in application code.
+   */
+  var ngHmrMode: boolean | undefined;
+}
+
+// Export an empty object to ensure this file is treated as an ES module, allowing augmentation of the global scope.
+export {};

packages/core/test/acceptance/defer_spec.ts

@@ -49,6 +49,8 @@ import {ActivatedRoute, provideRouter, Router, RouterOutlet} from '@angular/rout
 import {ChainedInjector} from '@angular/core/src/render3/chained_injector';
 import {global} from '../../src/util/global';
 import {TimerScheduler} from '@angular/core/src/defer/timer_scheduler';
+import {Console} from '../../src/console';
+import {formatRuntimeErrorCode, RuntimeErrorCode} from '../../src/errors';
 
 /**
  * Clears all associated directive defs from a given component class.
@@ -137,6 +139,25 @@ class FakeTimerScheduler {
   }
 }
 
+@Injectable()
+export class DebugConsole extends Console {
+  logs: string[] = [];
+  override log(message: string) {
+    this.logs.push(message);
+  }
+  override warn(message: string) {
+    this.logs.push(message);
+  }
+}
+
+/**
+ * Provides a debug console instance that allows to capture all
+ * produces messages for testing purposes.
+ */
+export function withDebugConsole() {
+  return [{provide: Console, useClass: DebugConsole}];
+}
+
 /**
  * Given a template, creates a component fixture and returns
  * a set of helper functions to trigger rendering of prefetching
@@ -534,6 +555,75 @@ describe('@defer', () => {
     });
   });
 
+  describe('with HMR', () => {
+    beforeEach(() => {
+      globalThis['ngHmrMode'] = true;
+    });
+
+    afterEach(() => {
+      globalThis['ngHmrMode'] = undefined;
+    });
+
+    it('should produce a message into a console about eagerly loaded deps', async () => {
+      @Component({
+        selector: 'simple-app',
+        template: `
+          @defer (when true) {
+            Defer block #1
+          }
+          @defer (on immediate) {
+            Defer block #2
+          }
+          @defer (when true) {
+            Defer block #3
+          }
+        `,
+      })
+      class MyCmp {}
+
+      TestBed.configureTestingModule({providers: [withDebugConsole()]});
+      const fixture = TestBed.createComponent(MyCmp);
+      fixture.detectChanges();
+
+      // Wait for all async actions to complete.
+      await allPendingDynamicImports();
+      fixture.detectChanges();
+
+      // Make sure that the HMR message is present in the console and there is
+      // only a single instance of a message.
+      const console = TestBed.inject(Console) as DebugConsole;
+      const errorCode = formatRuntimeErrorCode(RuntimeErrorCode.DEFER_IN_HMR_MODE);
+      const hmrMessages = console.logs.filter((log) => log.indexOf(errorCode) > -1);
+      expect(hmrMessages.length).withContext('HMR message should be present once').toBe(1);
+
+      const textContent = fixture.nativeElement.textContent;
+      expect(textContent).toContain('Defer block #1');
+      expect(textContent).toContain('Defer block #2');
+      expect(textContent).toContain('Defer block #3');
+    });
+
+    it('should not produce a message about eagerly loaded deps if no defer blocks are present', () => {
+      @Component({
+        selector: 'simple-app',
+        template: `No defer blocks`,
+      })
+      class MyCmp {}
+
+      TestBed.configureTestingModule({providers: [withDebugConsole()]});
+      const fixture = TestBed.createComponent(MyCmp);
+      fixture.detectChanges();
+
+      // Make sure that there were no HMR messages present in the console, because
+      // there were no defer blocks in a template.
+      const console = TestBed.inject(Console) as DebugConsole;
+      const errorCode = formatRuntimeErrorCode(RuntimeErrorCode.DEFER_IN_HMR_MODE);
+      const hmrMessages = console.logs.filter((log) => log.indexOf(errorCode) > -1);
+      expect(hmrMessages.length).withContext('HMR message should *not* be present').toBe(0);
+
+      expect(fixture.nativeElement.textContent).toContain('No defer blocks');
+    });
+  });
+
   describe('`on` conditions', () => {
     it('should support `on immediate` condition', async () => {
       @Component({