fix(core): produce an error when incremental hydration is expected, but not configured (#61741)

AndrewKushnir · kirjs · commit b1d960d082c6 · 2025-05-30T11:14:23.000-04:00
This commit updates runtime logic to produce an error when there are some `@defer` blocks with `hydrate` triggers, but the incremental hydration is not enabled via `withIncrementalHydration()`. Previously the check was only detecting the case when `withIncrementalHydration()` is present on the server, but missing on the client. With the change in this commit, the check would be performed on the server as well. PR Close #61741
diff --git a/packages/core/src/defer/instructions.ts b/packages/core/src/defer/instructions.ts
@@ -65,6 +65,7 @@ import {
   triggerPrefetching,
   triggerResourceLoading,
   shouldAttachTrigger,
+  hasHydrateTriggers,
 } from './triggering';
 import {formatRuntimeError, RuntimeErrorCode} from '../errors';
 import {Console} from '../console';
@@ -138,8 +139,13 @@ export function ɵɵdefer(
   if (tView.firstCreatePass) {
     performanceMarkFeature('NgDefer');
 
-    if (ngDevMode && typeof ngHmrMode !== 'undefined' && ngHmrMode) {
-      logHmrWarning(injector);
+    if (ngDevMode) {
+      if (typeof ngHmrMode !== 'undefined' && ngHmrMode) {
+        logHmrWarning(injector);
+      }
+      if (hasHydrateTriggers(flags)) {
+        assertIncrementalHydrationIsConfigured(injector);
+      }
     }
 
     const tDetails: TDeferBlockDetails = {
@@ -193,8 +199,6 @@ export function ɵɵdefer(
 
   let registry: DehydratedBlockRegistry | null = null;
   if (ssrUniqueId !== null) {
-    ngDevMode && assertIncrementalHydrationIsConfigured(injector);
-
     // Store this defer block in the registry, to have an access to
     // internal data structures from hydration runtime code.
     registry = injector.get(DEHYDRATED_BLOCK_REGISTRY);
diff --git a/packages/core/src/defer/triggering.ts b/packages/core/src/defer/triggering.ts
@@ -595,6 +595,14 @@ export function shouldAttachTrigger(triggerType: TriggerType, lView: LView, tNod
   return !(typeof ngServerMode !== 'undefined' && ngServerMode);
 }
 
+/** Whether a given defer block has `hydrate` triggers. */
+export function hasHydrateTriggers(flags: TDeferDetailsFlags | null | undefined): boolean {
+  return (
+    flags != null &&
+    (flags & TDeferDetailsFlags.HasHydrateTriggers) === TDeferDetailsFlags.HasHydrateTriggers
+  );
+}
+
 /**
  * Defines whether a regular trigger logic (e.g. "on viewport") should be attached
  * to a defer block. This function defines a condition, which mutually excludes
@@ -606,24 +614,21 @@ function shouldAttachRegularTrigger(lView: LView, tNode: TNode): boolean {
 
   const tDetails = getTDeferBlockDetails(lView[TVIEW], tNode);
   const incrementalHydrationEnabled = isIncrementalHydrationEnabled(injector);
-  const hasHydrateTriggers =
-    tDetails.flags !== null &&
-    (tDetails.flags & TDeferDetailsFlags.HasHydrateTriggers) ===
-      TDeferDetailsFlags.HasHydrateTriggers;
+  const _hasHydrateTriggers = hasHydrateTriggers(tDetails.flags);
 
   // On the server:
   if (typeof ngServerMode !== 'undefined' && ngServerMode) {
     // Regular triggers are activated on the server when:
     //  - Either Incremental Hydration is *not* enabled
     //  - Or Incremental Hydration is enabled, but a given block doesn't have "hydrate" triggers
-    return !incrementalHydrationEnabled || !hasHydrateTriggers;
+    return !incrementalHydrationEnabled || !_hasHydrateTriggers;
   }
 
   // On the client:
   const lDetails = getLDeferBlockDetails(lView, tNode);
   const wasServerSideRendered = lDetails[SSR_UNIQUE_ID] !== null;
 
-  if (hasHydrateTriggers && wasServerSideRendered && incrementalHydrationEnabled) {
+  if (_hasHydrateTriggers && wasServerSideRendered && incrementalHydrationEnabled) {
     return false;
   }
   return true;
diff --git a/packages/platform-server/test/incremental_hydration_spec.ts b/packages/platform-server/test/incremental_hydration_spec.ts
@@ -2693,4 +2693,69 @@ describe('platform-server partial hydration integration', () => {
       expect(appHostNode.outerHTML).toContain(`<p id="hydrated">yup</p>`);
     });
   });
+
+  describe('misconfiguration', () => {
+    it('should throw an error when `withIncrementalHydration()` is missing in SSR setup', async () => {
+      @Component({
+        selector: 'app',
+        template: `
+          @defer (hydrate never) {
+            <div>Hydrate never block</div>
+          }
+        `,
+      })
+      class SimpleComponent {}
+
+      const appId = 'custom-app-id';
+      const providers = [{provide: APP_ID, useValue: appId}];
+
+      // Empty list, `withIncrementalHydration()` is not included intentionally.
+      const hydrationFeatures = () => [];
+
+      let producedError;
+      try {
+        await ssr(SimpleComponent, {envProviders: providers, hydrationFeatures});
+      } catch (error: unknown) {
+        producedError = error;
+      }
+      expect((producedError as Error).message).toContain('NG0508');
+    });
+
+    it('should throw an error when `withIncrementalHydration()` is missing in hydration setup', async () => {
+      @Component({
+        selector: 'app',
+        template: `
+          @defer (hydrate never) {
+            <div>Hydrate never block</div>
+          }
+        `,
+      })
+      class SimpleComponent {}
+
+      const appId = 'custom-app-id';
+      const providers = [{provide: APP_ID, useValue: appId}];
+
+      const hydrationFeatures = () => [withIncrementalHydration()];
+
+      const html = await ssr(SimpleComponent, {envProviders: providers, hydrationFeatures});
+
+      // Internal cleanup before we do server->client transition in this test.
+      resetTViewsFor(SimpleComponent);
+
+      ////////////////////////////////
+
+      let producedError;
+      try {
+        const doc = getDocument();
+        await prepareEnvironmentAndHydrate(doc, html, SimpleComponent, {
+          envProviders: [...providers, {provide: PLATFORM_ID, useValue: 'browser'}],
+          // Empty list, `withIncrementalHydration()` is not included intentionally.
+          hydrationFeatures: () => [],
+        });
+      } catch (error: unknown) {
+        producedError = error;
+      }
+      expect((producedError as Error).message).toContain('NG0508');
+    });
+  });
 });
