The Code That Breaks When Angular Goes Zoneless

Start with the notification, not the API name#

A zoneless review starts with one question: when this code changes something the template reads, which notification path schedules Angular?

The official zoneless guide names the notification paths: markForCheck, AsyncPipe, ComponentRef.setInput, updating a signal read in the template, bound host or template listeners, and attaching a dirty view. Code that changes template state outside those paths becomes the first review target.

Do not mechanically delete every NgZone.run() or runOutsideAngular() call. A better review target is stability code such as NgZone APIs onStable, onUnstable, onMicrotaskEmpty, or logic that treats isStable as the source of truth.

Alex Rickabaugh (Angular team) framed the implication on JS Party episode 310: 'To turn off Zone is an application-wide decision, because Zone either as a library kind of has to be wrapping your application or not.' Zoneless is not a per-component flag. It is a posture the whole app commits to, which is why the review starts with the notification path, not the API surface.

Timer code can be lifecycle-safe and still invisible#

This timer cleans itself up, but that does not make it zoneless-compatible. The problem is not the interval. The problem is that a plain field changes and nothing tells Angular that a template read became stale.

If the template reads the current time, make the value a signal unless there is a stronger reason to keep a plain field. That makes the dependency explicit and keeps the cleanup requirement visible.

export class ClockComponent {
  private readonly destroyRef = inject(DestroyRef);

  now = new Date();

  ngOnInit() {
    const intervalId = window.setInterval(() => {
      this.now = new Date();
    }, 1000);

    this.destroyRef.onDestroy(() => {
      window.clearInterval(intervalId);
    });
  }
}

export class ClockComponent {
  private readonly destroyRef = inject(DestroyRef);

  readonly now = signal(new Date());

  ngOnInit() {
    const intervalId = window.setInterval(() => {
      this.now.set(new Date());
    }, 1000);

    this.destroyRef.onDestroy(() => {
      window.clearInterval(intervalId);
    });
  }
}

A safe subscription is not automatically a visible update#

takeUntilDestroyed fixes a lifecycle problem. It does not, by itself, notify Angular that a plain field assigned inside the subscription should refresh the template.

For template reads, the cleaner boundary is AsyncPipe or toSignal. If a plain field must remain because the component is adapting legacy code, put markForCheck() next to the assignment so the notification path is visible.

export class OrdersBadgeComponent {
  private readonly orders = inject(OrdersService);
  private readonly destroyRef = inject(DestroyRef);

  count = 0;

  ngOnInit() {
    this.orders.count$
      .pipe(takeUntilDestroyed(this.destroyRef))
      .subscribe((count) => {
        this.count = count;
      });
  }
}

export class OrdersBadgeComponent {
  private readonly orders = inject(OrdersService);

  readonly count = toSignal(this.orders.count$, {
    initialValue: 0,
  });
}

export class OrdersBadgeComponent {
  private readonly orders = inject(OrdersService);
  private readonly cdr = inject(ChangeDetectorRef);
  private readonly destroyRef = inject(DestroyRef);

  count = 0;

  ngOnInit() {
    this.orders.count$
      .pipe(takeUntilDestroyed(this.destroyRef))
      .subscribe((count) => {
        this.count = count;
        this.cdr.markForCheck();
      });
  }
}

Reactive forms need an explicit bridge#

Reactive forms remain a mature default. The zoneless caveat is narrower: if the template derives UI state from status, valid, errors, or a custom validation signal, make the notification path visible.

Convert only the form observable the template needs into a signal. The form model stays a form model, and the template gets a tracked value.

export class CheckoutFormComponent {
  private readonly fb = inject(NonNullableFormBuilder);

  readonly form = this.fb.group({
    email: '',
  });

  readonly status = toSignal(
    this.form.statusChanges.pipe(startWith(this.form.status)),
    { initialValue: this.form.status }
  );

  readonly canSubmit = computed(() => this.status() === 'VALID');
}

Third-party callbacks need an adapter boundary#

Charts, editors, maps, drag-and-drop packages, and custom overlays are good spike targets because they often mix DOM work, timers, observers, and callbacks that the Angular component did not design.

Do not scatter markForCheck() across callback bodies. Create a small adapter boundary: the third-party event enters one place, updates a signal or explicitly marks the view, and registers teardown.

export class SalesChartHostComponent {
  private readonly chart = inject(SalesChartAdapter);
  private readonly destroyRef = inject(DestroyRef);

  readonly selectedPoint = signal<ChartPoint | null>(null);

  ngAfterViewInit() {
    const unsubscribe = this.chart.onPointClick((point) => {
      this.selectedPoint.set(point);
    });

    this.destroyRef.onDestroy(unsubscribe);
  }
}

Tests should stop hiding missed notifications#

A test suite can make zoneless look safer than it is if every assertion forces another fixture.detectChanges(). That proves the template can render after manual change detection, not that production code notified Angular.

A spike needs focused tests that configure zoneless behavior and then use whenStable() after the action. If that fails, the component changed a template value without one of the notification paths.

The Angular team has been explicit about the direction in RFC #66779: zoneless 'has created a requirement that components explicitly use ChangeDetectionStrategy.OnPush or at least be OnPush compatible.' Tests that hide that requirement let production code drift past the spike.

@Component({
  selector: 'app-counter-badge',
  standalone: true,
  template: `<span>{{ count() }}</span>`,
})
class CounterBadgeComponent {
  readonly count = signal(0);

  setCountForTest(count: number) {
    this.count.set(count);
  }
}

beforeEach(() => {
  TestBed.configureTestingModule({
    imports: [CounterBadgeComponent],
    providers: [provideZonelessChangeDetection()],
  });
});

it('waits for Angular instead of forcing a second detectChanges', async () => {
  const fixture = TestBed.createComponent(CounterBadgeComponent);
  fixture.detectChanges();

  fixture.componentInstance.setCountForTest(3);
  await fixture.whenStable();

  expect(fixture.nativeElement.textContent).toContain('3');
});

The output should be a fix list, not a claim#

Do not end a zoneless spike with 'works' or 'does not work'. End with a small table that names the exact broken pattern, the notification path it should use, and whether the fix belongs in the component, a shared adapter, or a dependency upgrade.

That is the difference between adopting a modern Angular default and starting a risky migration campaign.