refactor(core): Make the zoneless-by-default change a flag flip

This makes the zoneless-by-default change a flag flip that can be individually enabled in tests, createApplication, and bootstrapModule for gradual rollout. In addition, the "require on CD provider" check is also made individually flippable for gradual rollout.
atscott · Jul 8, 2025 · Sep 16, 2025 · Sep 16, 2025 · 726c0bbf0332bc9c49091cc83957aeddc5383f5e
commit 726c0bbf0332bc9c49091cc83957aeddc5383f5e
diff --git a/packages/core/src/application/create_application.ts b/packages/core/src/application/create_application.ts
@@ -21,6 +21,9 @@ import {ProfilerEvent} from '../render3/profiler_types';
 import {errorHandlerEnvironmentInitializer} from '../error_handler';
 import {RuntimeError, RuntimeErrorCode} from '../errors';
 import {PlatformRef} from '../platform/platform_ref';
+import {internalProvideZoneChangeDetection} from '../change_detection/scheduling/ng_zone_scheduling';
+
+const ZONELESS_BY_DEFAULT = true;
 
 /**
  * Internal create application API that implements the core application creation logic and optional
@@ -64,6 +67,7 @@ export function internalCreateApplication(config: {
     // bootstrap level as well as providers passed to the bootstrap call by a user.
     const allAppProviders = [
       provideZonelessChangeDetectionInternal(),
+      ZONELESS_BY_DEFAULT ? [] : internalProvideZoneChangeDetection({}),
       errorHandlerEnvironmentInitializer,
       ...(appProviders || []),
     ];

diff --git a/packages/core/src/change_detection/scheduling/ng_zone_scheduling.ts b/packages/core/src/change_detection/scheduling/ng_zone_scheduling.ts
@@ -11,13 +11,11 @@ import {Subscription} from 'rxjs';
 import {ApplicationRef, ApplicationRefDirtyFlags} from '../../application/application_ref';
 import {
   ENVIRONMENT_INITIALIZER,
-  EnvironmentInjector,
   EnvironmentProviders,
   inject,
   Injectable,
   InjectionToken,
   makeEnvironmentProviders,
-  provideEnvironmentInitializer,
   StaticProvider,
 } from '../../di';
 import {RuntimeError, RuntimeErrorCode} from '../../errors';
@@ -28,12 +26,11 @@ import {InternalNgZoneOptions} from '../../zone/ng_zone';
 
 import {
   ChangeDetectionScheduler,
-  ZONELESS_SCHEDULER_DISABLED,
   ZONELESS_ENABLED,
   SCHEDULE_IN_ROOT_ZONE,
 } from './zoneless_scheduling';
 import {SCHEDULE_IN_ROOT_ZONE_DEFAULT} from './flags';
-import {INTERNAL_APPLICATION_ERROR_HANDLER, ErrorHandler} from '../../error_handler';
+import {INTERNAL_APPLICATION_ERROR_HANDLER} from '../../error_handler';
 
 @Injectable({providedIn: 'root'})
 export class NgZoneChangeDetectionScheduler {

diff --git a/packages/core/src/platform/bootstrap.ts b/packages/core/src/platform/bootstrap.ts
@@ -28,7 +28,8 @@ import {stringify} from '../util/stringify';
 import {isPromise} from '../util/lang';
 import {PendingTasksInternal} from '../pending_tasks_internal';
 
-const REQUIRE_ONE_CD_PROVIDER = false;
+const REQUIRE_ONE_CD_PROVIDER_CREATE_APPLICATION = false;
+const REQUIRE_ONE_CD_PROVIDER_BOOTSTRAP_MODULE = false;
 
 /**
  * InjectionToken to control root component bootstrap behavior.
@@ -104,8 +105,11 @@ export function bootstrap<M>(
           ),
         );
       }
-      if (REQUIRE_ONE_CD_PROVIDER) {
-        if (!envInjector.get(PROVIDED_ZONELESS) && !envInjector.get(PROVIDED_NG_ZONE)) {
+      if (!envInjector.get(PROVIDED_ZONELESS) && !envInjector.get(PROVIDED_NG_ZONE)) {
+        if (
+          (REQUIRE_ONE_CD_PROVIDER_CREATE_APPLICATION && isApplicationBootstrapConfig(config)) ||
+          (REQUIRE_ONE_CD_PROVIDER_BOOTSTRAP_MODULE && !isApplicationBootstrapConfig(config))
+        ) {
           throw new Error(
             'Missing change detection configuration: ' +
               'please add either `provideZoneChangeDetection()` or `provideZonelessChangeDetection()` ' +

diff --git a/packages/core/src/platform/platform_ref.ts b/packages/core/src/platform/platform_ref.ts
@@ -18,7 +18,13 @@ import {NgModuleFactory, NgModuleRef} from '../linker/ng_module_factory';
 import {createNgModuleRefWithProviders} from '../render3/ng_module_ref';
 import {bootstrap, setModuleBootstrapImpl} from './bootstrap';
 import {PLATFORM_DESTROY_LISTENERS} from './platform_destroy_listeners';
-import {internalProvideZoneChangeDetection} from '../change_detection/scheduling/ng_zone_scheduling';
+import {
+  getNgZoneOptions,
+  internalProvideZoneChangeDetection,
+} from '../change_detection/scheduling/ng_zone_scheduling';
+import {getNgZone} from '../zone/ng_zone';
+
+const ZONELESS_BY_DEFAULT = true;
 
 // Holds the set of providers to be used for the *next* application to be bootstrapped.
 // Used only for providing the zone related providers by default with `downgradeModule`.
@@ -55,8 +61,20 @@ export class PlatformRef {
     moduleFactory: NgModuleFactory<M>,
     options?: BootstrapOptions,
   ): Promise<NgModuleRef<M>> {
+    const defaultZoneCdProviders = [];
+    if (!ZONELESS_BY_DEFAULT) {
+      const ngZoneFactory = () =>
+        getNgZone(options?.ngZone, {
+          ...getNgZoneOptions({
+            eventCoalescing: options?.ngZoneEventCoalescing,
+            runCoalescing: options?.ngZoneRunCoalescing,
+          }),
+        });
+      defaultZoneCdProviders.push(internalProvideZoneChangeDetection({ngZoneFactory}));
+    }
     const allAppProviders = [
       provideZonelessChangeDetectionInternal(),
+      ...defaultZoneCdProviders,
       ...(_additionalApplicationProviders ?? []),
       errorHandlerEnvironmentInitializer,
     ];

diff --git a/packages/core/test/bundling/animations-standalone/bundle.golden_symbols.json b/packages/core/test/bundling/animations-standalone/bundle.golden_symbols.json
@@ -175,6 +175,7 @@
       "NgModuleRef",
       "NgOnChangesFeatureImpl",
       "NgZone",
+      "NgZoneChangeDetectionScheduler",
       "NodeInjector",
       "NodeInjectorDestroyRef",
       "NodeInjectorFactory",
@@ -268,9 +269,11 @@
       "WebAnimationsPlayer",
       "WebAnimationsStyleNormalizer",
       "XhrFactory",
+      "ZONELESS_BY_DEFAULT",
       "ZONELESS_ENABLED",
       "ZONELESS_SCHEDULER_DISABLED",
       "ZoneAwareEffectScheduler",
+      "ZoneStablePendingTask",
       "\\u0275PRE_STYLE",
       "\\u0275\\u0275defineComponent",
       "\\u0275\\u0275defineInjectable",
@@ -591,6 +594,7 @@
       "getNearestLContainer",
       "getNextLContainer",
       "getNgDirectiveDef",
+      "getNgZoneOptions",
       "getNodeInjectable",
       "getNullInjector",
       "getOrBorrowReactiveLViewConsumer",
@@ -657,6 +661,7 @@
       "instructionState",
       "internalCreateApplication",
       "internalImportProvidersFrom",
+      "internalProvideZoneChangeDetection",
       "interpolateParams",
       "invalidCssUnitValue",
       "invalidDefinition",

diff --git a/packages/core/test/bundling/defer/bundle.golden_symbols.json b/packages/core/test/bundling/defer/bundle.golden_symbols.json
@@ -67,8 +67,6 @@
       "shimStylesContent"
     ],
     "lazy": [
-      "DeferComponent",
-      "_DeferComponent",
       "AFTER_RENDER_SEQUENCES_TO_ADD",
       "ANIMATIONS",
       "APP_BOOTSTRAP_LISTENER",
@@ -190,6 +188,7 @@
       "NgModuleRef",
       "NgOnChangesFeatureImpl",
       "NgZone",
+      "NgZoneChangeDetectionScheduler",
       "NodeInjector",
       "NodeInjectorDestroyRef",
       "NodeInjectorFactory",
@@ -252,9 +251,11 @@
       "VIEW_REFS",
       "ViewEncapsulation",
       "ViewRef",
+      "ZONELESS_BY_DEFAULT",
       "ZONELESS_ENABLED",
       "ZONELESS_SCHEDULER_DISABLED",
       "ZoneAwareEffectScheduler",
+      "ZoneStablePendingTask",
       "\\u0275\\u0275advance",
       "\\u0275\\u0275defer",
       "\\u0275\\u0275deferWhen",
@@ -515,6 +516,7 @@
       "getNearestLContainer",
       "getNextLContainer",
       "getNgDirectiveDef",
+      "getNgZoneOptions",
       "getNodeInjectable",
       "getNullInjector",
       "getOrBorrowReactiveLViewConsumer",
@@ -583,6 +585,7 @@
       "instructionState",
       "internalCreateApplication",
       "internalImportProvidersFrom",
+      "internalProvideZoneChangeDetection",
       "invokeAllTriggerCleanupFns",
       "invokeDirectivesHostBindings",
       "invokeHostBindingsInCreationMode",
@@ -790,7 +793,9 @@
       "wasLastNodeCreated",
       "writeDirectClass",
       "writeDirectStyle",
-      "writeToDirectiveInput"
+      "writeToDirectiveInput",
+      "DeferComponent",
+      "_DeferComponent"
     ]
   }
 }
diff --git a/packages/core/test/bundling/hydration/bundle.golden_symbols.json b/packages/core/test/bundling/hydration/bundle.golden_symbols.json
@@ -157,6 +157,7 @@
       "NgModuleRef",
       "NgOnChangesFeatureImpl",
       "NgZone",
+      "NgZoneChangeDetectionScheduler",
       "NodeInjector",
       "NodeInjectorDestroyRef",
       "NodeInjectorFactory",
@@ -232,9 +233,11 @@
       "ViewEncapsulation",
       "ViewRef",
       "XhrFactory",
+      "ZONELESS_BY_DEFAULT",
       "ZONELESS_ENABLED",
       "ZONELESS_SCHEDULER_DISABLED",
       "ZoneAwareEffectScheduler",
+      "ZoneStablePendingTask",
       "\\u0275\\u0275defineComponent",
       "\\u0275\\u0275defineInjectable",
       "\\u0275\\u0275directiveInject",
@@ -532,6 +535,7 @@
       "getNextLContainer",
       "getNgContainerSize",
       "getNgDirectiveDef",
+      "getNgZoneOptions",
       "getNoOffsetIndex",
       "getNodeInjectable",
       "getNullInjector",
@@ -602,6 +606,7 @@
       "instructionState",
       "internalCreateApplication",
       "internalImportProvidersFrom",
+      "internalProvideZoneChangeDetection",
       "invokeDirectivesHostBindings",
       "invokeHostBindingsInCreationMode",
       "isAngularZoneProperty",

diff --git a/packages/core/test/bundling/router/bundle.golden_symbols.json b/packages/core/test/bundling/router/bundle.golden_symbols.json
@@ -191,6 +191,7 @@
       "NgModuleRef",
       "NgOnChangesFeatureImpl",
       "NgZone",
+      "NgZoneChangeDetectionScheduler",
       "NoLeftoversInUrl",
       "NoMatch",
       "NodeInjector",
@@ -318,9 +319,11 @@
       "ViewRef",
       "XSS_SECURITY_URL",
       "XhrFactory",
+      "ZONELESS_BY_DEFAULT",
       "ZONELESS_ENABLED",
       "ZONELESS_SCHEDULER_DISABLED",
       "ZoneAwareEffectScheduler",
+      "ZoneStablePendingTask",
       "\\u0275EmptyOutletComponent",
       "\\u0275\\u0275NgOnChangesFeature",
       "\\u0275\\u0275attribute",
@@ -789,6 +792,7 @@
       "getNextLContainer",
       "getNgDirectiveDef",
       "getNgModuleDef",
+      "getNgZoneOptions",
       "getNodeInjectable",
       "getNullInjector",
       "getOrBorrowReactiveLViewConsumer",
@@ -885,6 +889,7 @@
       "instructionState",
       "internalCreateApplication",
       "internalImportProvidersFrom",
+      "internalProvideZoneChangeDetection",
       "interpolation1",
       "invokeDirectivesHostBindings",
       "invokeHostBindingsInCreationMode",

diff --git a/packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json b/packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json
@@ -128,6 +128,7 @@
       "NgModuleRef",
       "NgOnChangesFeatureImpl",
       "NgZone",
+      "NgZoneChangeDetectionScheduler",
       "NodeInjector",
       "NodeInjectorDestroyRef",
       "NodeInjectorFactory",
@@ -191,9 +192,11 @@
       "ViewEncapsulation",
       "ViewRef",
       "XhrFactory",
+      "ZONELESS_BY_DEFAULT",
       "ZONELESS_ENABLED",
       "ZONELESS_SCHEDULER_DISABLED",
       "ZoneAwareEffectScheduler",
+      "ZoneStablePendingTask",
       "\\u0275\\u0275defineComponent",
       "\\u0275\\u0275defineInjectable",
       "\\u0275\\u0275directiveInject",
@@ -432,6 +435,7 @@
       "getNearestLContainer",
       "getNextLContainer",
       "getNgDirectiveDef",
+      "getNgZoneOptions",
       "getNodeInjectable",
       "getNullInjector",
       "getOrBorrowReactiveLViewConsumer",
@@ -489,6 +493,7 @@
       "instructionState",
       "internalCreateApplication",
       "internalImportProvidersFrom",
+      "internalProvideZoneChangeDetection",
       "invokeDirectivesHostBindings",
       "invokeHostBindingsInCreationMode",
       "isAngularZoneProperty",

diff --git a/packages/core/testing/src/test_bed_compiler.ts b/packages/core/testing/src/test_bed_compiler.ts
@@ -42,6 +42,7 @@ import {
   ɵgetInjectableDef as getInjectableDef,
   ɵInternalEnvironmentProviders as InternalEnvironmentProviders,
   ɵprovideZonelessChangeDetectionInternal as provideZonelessChangeDetectionInternal,
+  ɵinternalProvideZoneChangeDetection as internalProvideZoneChangeDetection,
   ɵisComponentDefPendingResolution,
   ɵisEnvironmentProviders as isEnvironmentProviders,
   ɵNG_COMP_DEF as NG_COMP_DEF,
@@ -91,6 +92,8 @@ enum TestingModuleOverride {
   OVERRIDE_TEMPLATE,
 }
 
+const ZONELESS_BY_DEFAULT = true;
+
 function isTestingModuleOverride(value: unknown): value is TestingModuleOverride {
   return (
     value === TestingModuleOverride.DECLARATION || value === TestingModuleOverride.OVERRIDE_TEMPLATE
@@ -935,6 +938,7 @@ export class TestBedCompiler {
       providers: [
         ...this.rootProviderOverrides,
         provideZonelessChangeDetectionInternal(),
+        ZONELESS_BY_DEFAULT ? [] : internalProvideZoneChangeDetection({}),
         TestBedApplicationErrorHandler,
         {
           provide: ENVIRONMENT_INITIALIZER,

diff --git a/packages/platform-browser/testing/src/browser.ts b/packages/platform-browser/testing/src/browser.ts
@@ -12,12 +12,15 @@ import {
   NgModule,
   StaticProvider,
   ɵprovideZonelessChangeDetectionInternal as provideZonelessChangeDetectionInternal,
+  ɵinternalProvideZoneChangeDetection as internalProvideZoneChangeDetection,
   PlatformRef,
 } from '@angular/core';
 import {TestComponentRenderer} from '@angular/core/testing';
 import {BrowserModule, platformBrowser} from '../../index';
 import {DOMTestComponentRenderer} from './dom_test_component_renderer';
 
+const ZONELESS_BY_DEFAULT = true;
+
 /**
  * Platform for testing
  *
@@ -36,6 +39,7 @@ export const platformBrowserTesting: (extraProviders?: StaticProvider[]) => Plat
   providers: [
     {provide: APP_ID, useValue: 'a'},
     provideZonelessChangeDetectionInternal(),
+    ZONELESS_BY_DEFAULT ? [] : internalProvideZoneChangeDetection({}),
     ɵprovideFakePlatformNavigation(),
     {provide: TestComponentRenderer, useClass: DOMTestComponentRenderer},
   ],