feat(platform-browser): Warns on conflicting hydration and blocking navigation (#62963)

SkyZeroZx · crisbeto · commit 52b8e07d6e56 · 2025-08-05T18:16:10.000+02:00
Adds an internal token to detect when both hydration and blocking initial navigation are enabled. Logs a warning during app initialization if this unsupported combination is found, helping developers avoid misconfiguration and potential runtime issues. PR Close #62963
diff --git a/packages/core/src/core_private_export.ts b/packages/core/src/core_private_export.ts
@@ -93,6 +93,7 @@ export {
   IS_HYDRATION_DOM_REUSE_ENABLED as ɵIS_HYDRATION_DOM_REUSE_ENABLED,
   IS_INCREMENTAL_HYDRATION_ENABLED as ɵIS_INCREMENTAL_HYDRATION_ENABLED,
   JSACTION_BLOCK_ELEMENT_MAP as ɵJSACTION_BLOCK_ELEMENT_MAP,
+  IS_ENABLED_BLOCKING_INITIAL_NAVIGATION as ɵIS_ENABLED_BLOCKING_INITIAL_NAVIGATION,
 } from './hydration/tokens';
 export {
   HydrationStatus as ɵHydrationStatus,
diff --git a/packages/core/src/hydration/tokens.ts b/packages/core/src/hydration/tokens.ts
@@ -13,7 +13,7 @@ import {InjectionToken} from '../di/injection_token';
  * during hydration is enabled.
  */
 export const IS_HYDRATION_DOM_REUSE_ENABLED = new InjectionToken<boolean>(
-  typeof ngDevMode === 'undefined' || !!ngDevMode ? 'IS_HYDRATION_DOM_REUSE_ENABLED' : '',
+  typeof ngDevMode === 'undefined' || ngDevMode ? 'IS_HYDRATION_DOM_REUSE_ENABLED' : '',
 );
 
 // By default (in client rendering mode), we remove all the contents
@@ -25,7 +25,7 @@ export const PRESERVE_HOST_CONTENT_DEFAULT = false;
  * retained during the bootstrap.
  */
 export const PRESERVE_HOST_CONTENT = new InjectionToken<boolean>(
-  typeof ngDevMode === 'undefined' || !!ngDevMode ? 'PRESERVE_HOST_CONTENT' : '',
+  typeof ngDevMode === 'undefined' || ngDevMode ? 'PRESERVE_HOST_CONTENT' : '',
   {
     providedIn: 'root',
     factory: () => PRESERVE_HOST_CONTENT_DEFAULT,
@@ -37,15 +37,15 @@ export const PRESERVE_HOST_CONTENT = new InjectionToken<boolean>(
  * is enabled.
  */
 export const IS_I18N_HYDRATION_ENABLED = new InjectionToken<boolean>(
-  typeof ngDevMode === 'undefined' || !!ngDevMode ? 'IS_I18N_HYDRATION_ENABLED' : '',
+  typeof ngDevMode === 'undefined' || ngDevMode ? 'IS_I18N_HYDRATION_ENABLED' : '',
 );
 
 /**
  * Internal token that indicates whether event replay support for SSR
  * is enabled.
  */
 export const IS_EVENT_REPLAY_ENABLED = new InjectionToken<boolean>(
-  typeof ngDevMode === 'undefined' || !!ngDevMode ? 'IS_EVENT_REPLAY_ENABLED' : '',
+  typeof ngDevMode === 'undefined' || ngDevMode ? 'IS_EVENT_REPLAY_ENABLED' : '',
 );
 
 export const EVENT_REPLAY_ENABLED_DEFAULT = false;
@@ -55,7 +55,7 @@ export const EVENT_REPLAY_ENABLED_DEFAULT = false;
  * is enabled.
  */
 export const IS_INCREMENTAL_HYDRATION_ENABLED = new InjectionToken<boolean>(
-  typeof ngDevMode === 'undefined' || !!ngDevMode ? 'IS_INCREMENTAL_HYDRATION_ENABLED' : '',
+  typeof ngDevMode === 'undefined' || ngDevMode ? 'IS_INCREMENTAL_HYDRATION_ENABLED' : '',
 );
 
 /**
@@ -68,3 +68,10 @@ export const JSACTION_BLOCK_ELEMENT_MAP = new InjectionToken<Map<string, Set<Ele
     factory: () => new Map<string, Set<Element>>(),
   },
 );
+
+/**
+ * Internal token that indicates whether the initial navigation is blocking in the application.
+ */
+export const IS_ENABLED_BLOCKING_INITIAL_NAVIGATION = new InjectionToken<boolean>(
+  typeof ngDevMode === 'undefined' || ngDevMode ? 'IS_ENABLED_BLOCKING_INITIAL_NAVIGATION' : '',
+);
diff --git a/packages/platform-browser/src/hydration.ts b/packages/platform-browser/src/hydration.ts
@@ -22,8 +22,8 @@ import {
   ɵwithI18nSupport,
   ɵZONELESS_ENABLED as ZONELESS_ENABLED,
   ɵwithIncrementalHydration,
+  ɵIS_ENABLED_BLOCKING_INITIAL_NAVIGATION as IS_ENABLED_BLOCKING_INITIAL_NAVIGATION,
 } from '@angular/core';
-
 import {RuntimeErrorCode} from './errors';
 
 /**
@@ -170,6 +170,35 @@ function provideZoneJsCompatibilityDetector(): Provider[] {
   ];
 }
 
+/**
+ * Returns an `ENVIRONMENT_INITIALIZER` token setup with a function
+ * that verifies whether enabledBlocking initial navigation is used in an application
+ * and logs a warning in a console if it's not compatible with hydration.
+ */
+function provideEnabledBlockingInitialNavigationDetector(): Provider[] {
+  return [
+    {
+      provide: ENVIRONMENT_INITIALIZER,
+      useValue: () => {
+        const isEnabledBlockingInitialNavigation = inject(IS_ENABLED_BLOCKING_INITIAL_NAVIGATION, {
+          optional: true,
+        });
+
+        if (isEnabledBlockingInitialNavigation) {
+          const console = inject(Console);
+          const message = formatRuntimeError(
+            RuntimeErrorCode.HYDRATION_CONFLICTING_FEATURES,
+            'Configuration error: found both hydration and enabledBlocking initial navigation ' +
+              'in the same application, which is a contradiction.',
+          );
+          console.warn(message);
+        }
+      },
+      multi: true,
+    },
+  ];
+}
+
 /**
  * Sets up providers necessary to enable hydration functionality for the application.
  *
@@ -251,6 +280,9 @@ export function provideClientHydration(
 
   return makeEnvironmentProviders([
     typeof ngDevMode !== 'undefined' && ngDevMode ? provideZoneJsCompatibilityDetector() : [],
+    typeof ngDevMode !== 'undefined' && ngDevMode
+      ? provideEnabledBlockingInitialNavigationDetector()
+      : [],
     withDomHydration(),
     featuresKind.has(HydrationFeatureKind.NoHttpTransferCache) || hasHttpTransferCacheOptions
       ? []
diff --git a/packages/router/src/provide_router.ts b/packages/router/src/provide_router.ts
@@ -28,6 +28,7 @@ import {
   runInInjectionContext,
   Type,
   ɵperformanceMarkFeature as performanceMarkFeature,
+  ɵIS_ENABLED_BLOCKING_INITIAL_NAVIGATION as IS_ENABLED_BLOCKING_INITIAL_NAVIGATION,
 } from '@angular/core';
 import {of, Subject} from 'rxjs';
 
@@ -347,6 +348,7 @@ export type InitialNavigationFeature =
  */
 export function withEnabledBlockingInitialNavigation(): EnabledBlockingInitialNavigationFeature {
   const providers = [
+    {provide: IS_ENABLED_BLOCKING_INITIAL_NAVIGATION, useValue: true},
     {provide: INITIAL_NAVIGATION, useValue: InitialNavigation.EnabledBlocking},
     provideAppInitializer(() => {
       const injector = inject(Injector);
