refactor(compiler-cli): output HMR initializer code

Adds the logic to the compiler that will output the HMR initializer code for each component, if enabled.
angular · crisbeto · Oct 10, 2024 · Oct 10, 2024 · Oct 10, 2024 · Oct 10, 2024
commit f6d1e52750359314749e427bb56ff2697d1e68cf
diff --git a/packages/bazel/src/ngc-wrapped/index.ts b/packages/bazel/src/ngc-wrapped/index.ts
@@ -92,6 +92,7 @@ export async function runOneBuild(
     'onlyExplicitDeferDependencyImports',
     'generateExtraImportsInLocalMode',
     '_enableLetSyntax',
+    '_enableHmr',
   ]);
 
   const userOverrides = Object.entries(userOptions)

diff --git a/packages/compiler-cli/src/ngtsc/annotations/common/src/util.ts b/packages/compiler-cli/src/ngtsc/annotations/common/src/util.ts
@@ -413,6 +413,7 @@ export function compileResults(
   additionalFields: CompileResult[] | null,
   deferrableImports: Set<ts.ImportDeclaration> | null,
   debugInfo: Statement | null = null,
+  hmrInitializer: Statement | null = null,
 ): CompileResult[] {
   const statements = def.statements;
 
@@ -424,6 +425,10 @@ export function compileResults(
     statements.push(debugInfo);
   }
 
+  if (hmrInitializer !== null) {
+    statements.push(hmrInitializer);
+  }
+
   const results = [
     fac,
     {

diff --git a/packages/compiler-cli/src/ngtsc/annotations/component/src/handler.ts b/packages/compiler-cli/src/ngtsc/annotations/component/src/handler.ts
@@ -10,6 +10,7 @@ import {
   AnimationTriggerNames,
   BoundTarget,
   compileClassDebugInfo,
+  compileClassHmrInitializer,
   compileComponentClassMetadata,
   compileComponentDeclareClassMetadata,
   compileComponentFromMetadata,
@@ -179,6 +180,7 @@ import {
 } from './util';
 import {getTemplateDiagnostics} from '../../../typecheck';
 import {JitDeclarationRegistry} from '../../common/src/jit_declaration_registry';
+import {extractHmrInitializerMeta} from './hmr';
 
 const EMPTY_ARRAY: any[] = [];
 
@@ -255,6 +257,7 @@ export class ComponentDecoratorHandler
     private readonly jitDeclarationRegistry: JitDeclarationRegistry,
     private readonly i18nPreserveSignificantWhitespace: boolean,
     private readonly strictStandalone: boolean,
+    private readonly enableHmr: boolean,
   ) {
     this.extractTemplateOptions = {
       enableI18nLegacyMessageIdFormat: this.enableI18nLegacyMessageIdFormat,
@@ -872,6 +875,9 @@ export class ComponentDecoratorHandler
           this.rootDirs,
           /* forbidOrphanRenderering */ this.forbidOrphanRendering,
         ),
+        hmrInitializerMeta: this.enableHmr
+          ? extractHmrInitializerMeta(node, this.reflector, this.rootDirs)
+          : null,
         template,
         providersRequiringFactory,
         viewProvidersRequiringFactory,
@@ -1613,6 +1619,10 @@ export class ComponentDecoratorHandler
       analysis.classDebugInfo !== null
         ? compileClassDebugInfo(analysis.classDebugInfo).toStmt()
         : null;
+    const hmrInitializer =
+      analysis.hmrInitializerMeta !== null
+        ? compileClassHmrInitializer(analysis.hmrInitializerMeta).toStmt()
+        : null;
     const deferrableImports = this.deferredSymbolTracker.getDeferrableImportDecls();
     return compileResults(
       fac,
@@ -1622,6 +1632,7 @@ export class ComponentDecoratorHandler
       inputTransformFields,
       deferrableImports,
       debugInfo,
+      hmrInitializer,
     );
   }
 
@@ -1695,6 +1706,10 @@ export class ComponentDecoratorHandler
       analysis.classDebugInfo !== null
         ? compileClassDebugInfo(analysis.classDebugInfo).toStmt()
         : null;
+    const hmrInitializer =
+      analysis.hmrInitializerMeta !== null
+        ? compileClassHmrInitializer(analysis.hmrInitializerMeta).toStmt()
+        : null;
     const deferrableImports = this.deferredSymbolTracker.getDeferrableImportDecls();
     return compileResults(
       fac,
@@ -1704,6 +1719,7 @@ export class ComponentDecoratorHandler
       inputTransformFields,
       deferrableImports,
       debugInfo,
+      hmrInitializer,
     );
   }
 

diff --git a/packages/compiler-cli/src/ngtsc/annotations/component/src/hmr.ts b/packages/compiler-cli/src/ngtsc/annotations/component/src/hmr.ts
@@ -0,0 +1,43 @@
+/*!
+ * @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
+ */
+
+import {R3HmrInitializerMetadata, WrappedNodeExpr} from '@angular/compiler';
+import {DeclarationNode, ReflectionHost} from '../../../reflection';
+import {relative} from 'path';
+
+/**
+ * Extracts the metadata necessary to generate an HMR initializer.
+ */
+export function extractHmrInitializerMeta(
+  clazz: DeclarationNode,
+  reflection: ReflectionHost,
+  rootDirs: readonly string[],
+): R3HmrInitializerMetadata | null {
+  if (!reflection.isClass(clazz)) {
+    return null;
+  }
+
+  // Attempt to generate a project-relative path before falling back to the full path.
+  let filePath = clazz.getSourceFile().fileName;
+  for (const rootDir of rootDirs) {
+    const relativePath = relative(rootDir, filePath);
+    if (!relativePath.startsWith('..')) {
+      filePath = relativePath;
+      break;
+    }
+  }
+
+  const meta: R3HmrInitializerMetadata = {
+    type: new WrappedNodeExpr(clazz.name),
+    className: clazz.name.text,
+    timestamp: Date.now() + '',
+    filePath,
+  };
+
+  return meta;
+}
diff --git a/packages/compiler-cli/src/ngtsc/annotations/component/src/metadata.ts b/packages/compiler-cli/src/ngtsc/annotations/component/src/metadata.ts
@@ -12,6 +12,7 @@ import {
   DeferBlockDepsEmitMode,
   R3ClassDebugInfo,
   R3ClassMetadata,
+  R3HmrInitializerMetadata,
   R3ComponentMetadata,
   R3DeferPerBlockDependency,
   R3DeferPerComponentDependency,
@@ -56,6 +57,7 @@ export interface ComponentAnalysisData {
   template: ParsedTemplateWithSource;
   classMetadata: R3ClassMetadata | null;
   classDebugInfo: R3ClassDebugInfo | null;
+  hmrInitializerMeta: R3HmrInitializerMetadata | null;
 
   inputs: ClassPropertyMapping<InputMapping>;
   inputFieldNamesFromMetadataArray: Set<string>;

diff --git a/packages/compiler-cli/src/ngtsc/annotations/component/test/component_spec.ts b/packages/compiler-cli/src/ngtsc/annotations/component/test/component_spec.ts
@@ -156,6 +156,7 @@ function setup(
     jitDeclarationRegistry,
     /* i18nPreserveSignificantWhitespace */ true,
     /* strictStandalone */ false,
+    /* enableHmr */ false,
   );
   return {reflectionHost, handler, resourceLoader, metaRegistry};
 }

diff --git a/packages/compiler-cli/src/ngtsc/core/api/src/options.ts b/packages/compiler-cli/src/ngtsc/core/api/src/options.ts
@@ -113,6 +113,13 @@ export interface InternalOptions {
    * @internal
    */
   _angularCoreVersion?: string;
+
+  /**
+   * Whether to enable the necessary code generation for hot module reloading.
+   *
+   * @internal
+   */
+  _enableHmr?: boolean;
 }
 
 /**

diff --git a/packages/compiler-cli/src/ngtsc/core/src/compiler.ts b/packages/compiler-cli/src/ngtsc/core/src/compiler.ts
@@ -390,6 +390,7 @@ export class NgCompiler {
   private readonly enableBlockSyntax: boolean;
   private readonly enableLetSyntax: boolean;
   private readonly angularCoreVersion: string | null;
+  private readonly enableHmr: boolean;
 
   /**
    * `NgCompiler` can be reused for multiple compilations (for resource-only changes), and each
@@ -462,6 +463,7 @@ export class NgCompiler {
     this.enableBlockSyntax = options['_enableBlockSyntax'] ?? true;
     this.enableLetSyntax = options['_enableLetSyntax'] ?? true;
     this.angularCoreVersion = options['_angularCoreVersion'] ?? null;
+    this.enableHmr = !!options['_enableHmr'];
     this.constructionDiagnostics.push(
       ...this.adapter.constructionDiagnostics,
       ...verifyCompatibleTypeCheckOptions(this.options),
@@ -1463,6 +1465,7 @@ export class NgCompiler {
         jitDeclarationRegistry,
         this.options.i18nPreserveWhitespaceForLegacyExtraction ?? true,
         !!this.options.strictStandalone,
+        this.enableHmr,
       ),
 
       // TODO(alxhub): understand why the cast here is necessary (something to do with `null`

diff --git a/packages/compiler-cli/test/ngtsc/ngtsc_spec.ts b/packages/compiler-cli/test/ngtsc/ngtsc_spec.ts
@@ -10519,6 +10519,69 @@ runInEachFileSystem((os: string) => {
       });
     });
 
+    describe('HMR initializer', () => {
+      it('should not generate an HMR initializer by default', () => {
+        env.write(
+          'test.ts',
+          `
+            import {Component} from '@angular/core';
+
+            @Component({
+              selector: 'cmp',
+              template: 'hello',
+              standalone: true,
+            })
+            export class Cmp {}
+          `,
+        );
+
+        env.driveMain();
+
+        const jsContents = env.getContents('test.js');
+        expect(jsContents).not.toContain('import.meta.hot');
+        expect(jsContents).not.toContain('replaceMetadata');
+      });
+
+      it('should generate an HMR initializer when enabled', () => {
+        env.write(
+          'tsconfig.json',
+          JSON.stringify({
+            extends: './tsconfig-base.json',
+            angularCompilerOptions: {
+              _enableHmr: true,
+            },
+          }),
+        );
+
+        env.write(
+          'test.ts',
+          `
+            import {Component} from '@angular/core';
+
+            @Component({
+              selector: 'cmp',
+              template: 'hello',
+              standalone: true,
+            })
+            export class Cmp {}
+          `,
+        );
+
+        env.driveMain();
+
+        const jsContents = env.getContents('test.js');
+
+        // We need a regex match here, because the file path changes based on
+        // the file system and the timestamp will be different for each test run.
+        expect(jsContents).toMatch(
+          /import\.meta\.hot && import\.meta\.hot\.on\("angular:component-update", d => { if \(d\.id == ".*test\.ts%40Cmp"\) {/,
+        );
+        expect(jsContents).toMatch(
+          /import\("\/@ng\/component\?c=.*test\.ts%40Cmp&t=\d+"\).then\(m => i0\.ɵɵreplaceMetadata\(Cmp, m\.default\)\);/,
+        );
+      });
+    });
+
     describe('tsickle compatibility', () => {
       it('should preserve fileoverview comments', () => {
         env.write(