DEV Community: Ilir Beqiri

Angular @let declarations: Smart Template Subscriptions

Ilir Beqiri — Mon, 02 Sep 2024 18:23:07 +0000

For some time now, Angular has been living in its momentum and the Angular team has proven that it cares about its community. In the Angular v17, and the following minor releases, the Angular team delivered many great features, with one that stood out most, even though in the developer preview, was the new built-in block template syntax that simplified working with templates.

In the recent version, two long-awaited issues in the Angular repo were closed. Angular major version, v18, shipped the Unified Control State Change Events amongst other features, and the minor version, v18.1, took advantage of the block template syntax by adding a new built-in feature to the template known as the Template Local Variables, denoted by @let block.

Check the official blog post to know more about how @let variables are defined, work, limitations, and how they update their values.

In simple terms, Template Local Variables, allow Angular developers to declare variables in their templates, just like we do in the component’s class, streamlining how we write the logic in the template thereby bringing alternatives to some old template patterns, and introducing new use cases that were covered in this article from @eneajaho.

The motivation for this article came from a Reddit thread questioning whether @let declarations were needed and why they should be used.

You can find the take of the main Angular contributor, Matthieu Riegler, about this topic here.

In this article, I want to show a use case of these local template variables I found useful on a project I work on, where I need no more do the “caching” with the RxJS shareReplay operator from the component’s class for using same piece of data in different template sections.

Let’s dive in 🚀.

RxJS “caching” with shareReplay operator

While developing web applications, the most common thing developers do is make HTTP requests. In Angular, HTTP communication is done through an observable-based API, the popular HttpClient. Since in most cases, the fetched data are bound in the template, developers follow the declarative approach with Async pipe as the best practice — automatically subscribes to the observable in the template, and unsubscribes when the component is destroyed 👇:

...
@Component({
  ...
  template: `
    ...
    <main>
      ...            👇
      @if (todo$ | async; as todo) {
        <p>Title: {{todo.title}}</p>
      }
    </main>
   ...
  `,
  standalone: true,
  ...
})
export class ShareReplayComponent {
  todo$ = inject(HttpClient)
    .get<Todo>('https://jsonplaceholder.typicode.com/todos/1');
}

But there are cases when we need the data from the same stream somewhere else in the template, so we bind the observable stream in the template with the Async pipe again 👇:

...
@Component({
  template: `
    ...
    <main>
      ...           👇
      @if (todo$ | async; as todo) {
        <p>Title: {{todo.title}}</p>
      }
    </main>

    <aside>
      ...            👇
      @if (todo$ | async; as todo) {
        <p>Is Completed: {{todo.completed}}</p>
      }
    </aside>
   ...    
  `,
  standalone: true,
})
export class ShareReplayComponent {
  todo$ = inject(HttpClient)
    .get<Todo>('https://jsonplaceholder.typicode.com/todos/1');
}

This results in having the same observable stream bound and subscribed in two different sections of the template thus having two, duplicate HTTP requests ongoing for fetching the same piece of data unnecessarily 👇:

A common solution to this case (I’ve seen) is caching the data from the first fired HTTP request using RxJS through the shareReplay operator:

...
@Component({
  template: `
    ...
    <main>
      ...            👇
      @if (todo$ | async; as todo) {
        <p>Title: {{todo.title}}</p>
      }
    </main>

    <aside>
      ...            👇
      @if (todo$ | async; as todo) {
        <p>Is Completed: {{todo.completed}}</p>
      }
    </aside>
   ...
  `,
  standalone: true,

})
export class ShareReplayComponent {
  todo$ = inject(HttpClient)
    .get<Todo>('https://jsonplaceholder.typicode.com/todos/1')
    .pipe(shareReplay(1)); 👈
}

This ensures that even though the same observable stream is bound and subscribed with the Async pipe in several places in the template, only one HTTP request will be triggered, and the response data gets cached 👇:

This pattern works fine but can we achieve this functionality more simply?

Let’s find out 💪.

@let declarations for streamlining

Although the RxJS solution works fine and fulfills our needs, the @let declarations introduced in Angular v18.1 offer a simpler, template-based alternative 👇:

...
@Component({
  template: `
    ...
    @let todo = todo$ | async; 👈
    <main>
      ...
      @if (todo) {
        <p>Title: {{todo.title}}</p>
      }
    </main>

    <aside>
      ...
      @if (todo) {
        <p>Is Completed: {{todo.completed}}</p>
      }
    </aside>
   ...
  `,
  standalone: true,

})
export class LetVariablesComponent {
  todo$ = inject(HttpClient)
    .get<Todo>('https://jsonplaceholder.typicode.com/todos/1');
}

As can be noticed, it offers a kind of “template-based caching” — bind and subscribe to the HTTP request observable only once in the template 👇:

As a result, no duplicate HTTP requests are outgoing, and no RxJS caching through the shareReplay operator is required. 🚀🚀

Note💡: This solution works when caching data for the template. The shareReplay operator is required if cached data is needed in the component’s class.

Special thanks to @kreuzerk and @eneajaho for the review.

Thanks for reading!

I hope you enjoyed it 🙌. If you liked the article please share it with your friends and colleagues.

For any questions or suggestions, feel free to comment below 👇.

If this article is interesting and useful to you, and you don’t want to miss future articles, follow me at @lilbeqiri, dev.to, or Medium. 📖

Model Inputs: Reactive Two-Way Binding

Ilir Beqiri — Wed, 28 Feb 2024 17:54:42 +0000

In Angular v17, the Angular team announced that signals graduated from the developer preview (except effects) as a stable and new reactivity primitive in the framework. Shortly after that, a high-level plan was published by the core members of the Angular team on a meetup (#NgGlühwein), showing the concrete, incremental steps that will follow to gradually integrate signals throughout the framework APIs that they best fit in and take advantage of 👇:

Then, not a while later, the team revealed publicly the reactivity roadmap, where you can track all the tiny steps the team is taking to fulfill each of the defined points shown in the plan above.

With the signals already stable on v17, the focus shifted to the second step in the plan: Signal I/O. The next two minor releases, Angular v17.1, and v17.2 released a few weeks ago, beyond the fact that they were minor releases, they have made a big splash in the community with the new signal APIs introduced in the framework:

input signals,
signal queries, and
model inputs.

You can read more about these APIs in the official blog post.

Those APIs integrate signals in nearly all component "APIs", leveraging the benefits they offer, thus paving the path to future signal-based components and zoneless change detection.

Both, signal queries and signal inputs, as per the name, provide a reactive, alternative API to decorator-based counterparts, and model inputs provide a reactive, alternative API for two-way data binding in Angular.

Currently, in the developer preview, those APIs will be recommended to be used once they are promoted to production-ready APIs in an upcoming version.

In this article, I will focus on model inputs, as a reactive alternative of two-way binding, and get to know the bonus feature introduced unexpectedly alongside them.

Let's dive in 🚀

Two-Way Binding

For many years now, two-way binding has been the simplest form of parent-child component communication in Angular. It is also widely known as banana-in-the-box - an illustrative name for the template syntactic sugar. Most of the time when we talk about two-way binding in Angular, we all think about the popular ngModel form directive:

@Component({
  selector: 'app-root',
  template: `
    // [(banana-in-the-box)]
               👇
    <input [(ngModel)]="name" />
  `,
})
export class AppComponent {
  name = '';
}

In a nutshell, two-way binding is a combination of property and event binding for bidirectional communication between components. Before model inputs, this two-way communication was possible through the decorator-based APIs, specifically @Input and @Output decorators as below 👇:

// child.component.ts
@Component({
  selector: 'app-child',
  ...
})
export class ChildComponent {
  @Input()
  counter: number = 0;

  @Output()
  counterChange = new EventEmitter<number>();

  changeValue(newValue: number) {
    this.counterChange.emit(newValue)
  }
}

// parent.component.ts
@Component({
  selector: 'app-parent',
  template: `
    // [(banana-in-the-box)]
                    👇
    <app-child [(counter)]="currentCount" />
  `,
})
export class ParentComponent {
  currentCount = 0;
}

In the code above, you can see that we only define the respective input and output properties but do not define an explicit relationship between them. The compiler is smart enough to detect the relationship through a naming convention: the @Output property must use the Change naming pattern where the is the name of the @Input property. If we check the compiled code for the implementation above before model inputs, it looks like the below 👇:

_ParentComponent.cmp = /* @__PURE__ */ defineComponent({ type: _ParentComponent, selectors: [["app-parent"]], standalone: true, features: [StandaloneFeature], decls: 1, vars: 1, consts: [[3, "counter", "counterChange"]], template: function ParentComponent_Template(rf, ctx) {
  if (rf & 1) {
    elementStart(0, "app-child", 0);
 👉 listener("counterChange", function ParentComponent_Template_app_child_counterChange_0_listener($event) {
      return ctx.currentCount = $event;
    });
    elementEnd();
  }
  if (rf & 2) {  👇
    property("counter", ctx.currentCount);
  }
}, dependencies: [ChildComponent], styles: ["\n\n/*# sourceMappingURL=parent.component.css.map */"] });

You can barely notice two functions of great importance: the property template instruction which binds the currentCount field to the counter input property, and the listener template instruction sets up an event and registers a listener which when executed updates the bound field's value.

This way, components on both ends are aware when the bound value changes but other logic in the component can't implicitly react to this change unless some manual work is done there:

// child.component.ts
@Component({
  selector: 'app-child',
  ...
})
export class ChildComponent {
  // using a setter
  _counter: number = 0;
  @Input()
  set counter(counter: number) { 👈
     this._counter = counter;
  }

  @Output()
  counterChange = new EventEmitter<number>();

  ...
}

// parent.component.ts
@Component({
  selector: 'app-parent',
  template: `
    // use standard property/event binding instead                    
    <app-child 
      [counter]="currentCount" 👈
      (counterChange)="onCounterChange($event)" /> 👈
  `,
})
export class ParentComponent {
  currentCount = 0;

  onCounterChange(value: number) {...}
}

As you can see, on the child end, a setter input is used to react whenever the bound value changes, and on the parent end, the banana-in-the-box syntax is replaced with the standard property and event binding instead so the parent will be able to listen for the value change and react accordingly.

The ngOnChanges lifecycle hook is an alternative to setter inputs.

And… there is no issue with this code, it has been proven to work over time, and serve very well.

Next, let's see what we get with model inputs 🐱‍🏍.

Model Inputs

Introduced in the Angular v17.2 minor release, as an ongoing effort of the Angular team to integrate signals to component I/O APIs, similar to decorator-based APIs, model inputs enable bidirectional communication between parent and child components. A key difference is that they provide a functional, signal-based, reactive API but still use the banana-in-the-box syntactic sugar in the template:

// child.component.ts
@Component({
  selector: 'app-child',
  ...
})
export class ChildComponent {
  counter= model(0); 👈

  changeValue(newValue: number) {
    this.counter.set(newValue) 👈
  }
}

// parent.component.ts
@Component({
  selector: 'app-parent',
  template: `      👇
    <app-child [(counter)]="currentCount" />
  `,
})
export class ParentComponent {
  currentCount = 0;
}

Now, instead of the developer defining the input and output properties, we call the model() function. It's the Angular Compiler that recognizes the API internally and defines the event and property bindings thus providing developers with a reactive public API for use. You can check the source code here 👇:

https://github.com/angular/angular/blob/69948e1256daf969e060c602f950c3c92e4a5e43/packages/compiler-cli/src/transformers/jit_transforms/initializer_api_transforms/model_function.ts#L34

To fulfill the two-way binding contract, the function returns a writable signal, thus enabling value updates on the events side of the binding. The generated compiler code looks like this 👇:

_ParentComponent.cmp = /* @__PURE__ */ defineComponent({ type: _ParentComponent, selectors: [["app-parent"]], standalone: true, features: [StandaloneFeature], decls: 3, vars: 1, consts: [[3, "counter", "counterChange"]], template: function ParentComponent_Template(rf, ctx) {
  if (rf & 1) {
    ... 👇
    twoWayListener("counterChange", function ParentComponent_Template_app_counter_counterChange_2_listener($event) {
      twoWayBindingSet(ctx.currentCount, $event) || (ctx.currentCount = $event);
      return $event;
    });  
  }
  if (rf & 2) {
    advance(2);
    twoWayProperty("counter", ctx.currentCount); 👈
  }
}, dependencies: [CounterComponent], styles: ["\n\n/*# sourceMappingURL=parent.component.css.map */"] });

The same naming convention/pattern is followed as before but now by the compiler itself. But in difference with the previous implementation, to achieve this functionality, a pair of new template instructions were introduced: twoWayProperty, and twoWayListener with twoWayBindingSet:

https://github.com/angular/angular/commit/3faf3e23d55b3e41cc43c4498393b01440f1cbb7
If you check the code behind these instructions, one can see they enhance the functionality of existing, listener, and property template instructions, with writable signal handling capabilities.

The twoWayProperty instruction uses the same logic as the property instruction but also does an extra check if the bound field is a writable signal or not, and reads the field value accordingly:

// compiled code
twoWayProperty("counter", ctx.currentCount); 👈

// implementation
export function ɵɵtwoWayProperty<T>(
    propName: string, value: T|WritableSignal<T>,
    sanitizer?: SanitizerFn|null): typeof ɵɵtwoWayProperty {
  if (isWritableSignal(value)) { 👈
    value = value();
  }

  const lView = getLView();
  const bindingIndex = nextBindingIndex();
  if (bindingUpdated(lView, bindingIndex, value)) {
    const tView = getTView();
    const tNode = getSelectedTNode();
    elementPropertyInternal(
        tView, tNode, lView, propName, value, lView[RENDERER], sanitizer, false);
    ngDevMode && storePropertyBindingMetadata(tView.data, tNode, propName, bindingIndex);
  }

  return ɵɵtwoWayProperty;
}

On the other hand, the twoWayListener instruction uses the same logic as the listener instruction, sets up the event, and registers an event listener. This listener itself, does not just update the bound field directly but does an extra check if the bound field is a writable signal or not (using twoWayBindingSet instruction), and then updates the field value accordingly:

// compiled code
twoWayListener("counterChange", function ParentComponent_Template_app_counter_counterChange_2_listener($event) {
👉 twoWayBindingSet(ctx.currentCount, $event) || (ctx.currentCount = $event);
    return $event;
});

// implementation
export function ɵɵtwoWayBindingSet<T>(target: unknown, value: T): boolean {
  const canWrite = isWritableSignal(target);
  canWrite && target.set(value);
  return canWrite;
}

export function ɵɵtwoWayListener(
    eventName: string, listenerFn: (e?: any) => any): typeof ɵɵtwoWayListener {
  const lView = getLView<{}|null>();
  const tView = getTView();
  const tNode = getCurrentTNode()!;
👉listenerInternal(tView, lView, lView[RENDERER], tNode, eventName, listenerFn);
  return ɵɵtwoWayListener;
}

So, in this way, these instructions enable exposing the bound field to the child component as a signal, specifically a writable signal, thus opening doors for all the benefits that signals provide.

But… if you stop and reason carefully about the implementation, you can find that alongside the model() function, surprisingly, a featurette (read: small feature) was shipped. What is interesting is that it was announced by one of the Angular stars, Matthieu Riegler in X 🚀:

// Detect dark theme var iframe = document.getElementById('tweet-1755890056261231000-944'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1755890056261231000&theme=dark" }

This is what the next section is all about. Let's go 💪.

Signal Double Bindings

In the simplest form, this means that: besides JavaScript's primitive values, developers can now bind a writable signal field in the template for two-way binding as follows:

// child.component.ts
@Component({
  selector: 'app-child',
  ...
})
export class ChildComponent {
  counter= model(0); 👈

  changeValue(newValue: number) {
    this.counter.set(newValue) 👈
  }
}

// parent.component.ts
@Component({
  selector: 'app-parent',
  template: `                  👇
    <app-child [(counter)]="currentCount" />
  `,
})
export class ParentComponent {
  currentCount = signal(0); 👈
}

Now, this leads to the point that a writable signal will work with the banana-in-the-box syntax on any component providing two-way binding.

Remember the ngModel form directive I mentioned earlier? It works perfectly fine there too. It offers another alternative to working with form controls and ways to react when the control's value changes:

@Component({
  selector: 'app-root',
  template: `
    // [(banana-in-the-box)]
               👇
    <input [(ngModel)]="name" />
  `,
})
export class AppComponent {
  name = signal('inputs');

  👇
  nickName = computed(() => `model-${this.name()}`)

  constructor() {
    👉 effect(() => console.log(this.name()))
  }
}

With this in place, we have a reactive way of sharing the state between parent and child components, and easier ways to run logic on both ends whenever the bound value changes.

A thing worth noting here is that, unlike the decorator-based approach, the expanded syntax of property/event binding is not supported when binding a writable signal:

...
@Component({
  selector: 'app-parent',
  template: `
    <app-child 
      [counter]="currentCount" 👈 // Type 'WritableSignal<number>' is not 
      (counterChange)="onCounterChange($event)" /> assignable to type 'number'
  `,
})
export class ParentComponent {
  currentCount = signal(0);
}

To understand why this happens, let's see the compiled code when binding a non-signal field 👇:

_ParentComponent.cmp = /* @__PURE__ */ defineComponent({ type: _ParentComponent, selectors: [["app-parent"]], standalone: true, features: [StandaloneFeature], decls: 1, vars: 1, consts: [[3, "counter", "counterChange"]], template: function ParentComponent_Template(rf, ctx) {
  if (rf & 1) {
    elementStart(0, "app-child", 0);
 👉 listener("counterChange", function ParentComponent_Template_app_child_counterChange_0_listener($event) {
      return ctx.currentCount = $event;
    });
    elementEnd();
  }
  if (rf & 2) {  👇
    property("counter", ctx.currentCount);
  }
}, dependencies: [ChildComponent], styles: ["\n\n/*# sourceMappingURL=parent.component.css.map */"] });

The reason behind this compile-time issue is that the classic template instructions, listener, and property are used for the standalone property and event binding in the template, having no extra logic for handling writable signals, thus restricted to using only non-signal fields for binding.

But it works if you unbox the signal value when property binding for the same reason when binding a non-signal field 👇:

...
@Component({
  selector: 'app-parent',
  template: `
    <app-child 
      [counter]="currentCount()" 👈 // unboxing the value
      (counterChange)="onCounterChange($event)" />
  `,
})
export class ParentComponent {
  currentCount = signal(0);

  onCounterChange(newCount: number) { this.currentCount.set(newCount);}
}

Hope that this is all clear 🤗.

Conclusion

Angular is evolving. Signals, as a framework-wide feature, are gradually being integrated into component APIs, as a part of a well-prepared plan, thus offering developers a better experience and new ways of authoring components, and reacting to state changes. The last two minor releases, v17.1 and v17.2, nearly completed the signal integration to component APIs by model inputs introducing signal-based two-way binding hence reactively sharing state between parent and child components. With currently introduced features, paving the path toward signal-based components, and zoneless change detection, the Angular community has reason to look forward to exciting future releases.

Special thanks to Enea Jahollari and Matthieu Riegler for the review.

Thanks for reading!

I hope you enjoyed it 🙌. If you liked the article please feel free to share it with your friends and colleagues.

For any questions or suggestions, feel free to comment below 👇.

If this article is interesting and useful to you, and you don't want to miss future articles, follow me at @lilbeqiri, dev.to, or Medium. 📖

Template-Level Lazy Loading in Angular

Ilir Beqiri — Tue, 13 Feb 2024 15:57:48 +0000

Working with a component-based framework such as Angular, you may witness that templates are a crucial building block of components. Thanks to the template's flexibility and the declarative APIs it supports, we can create highly dynamic web applications. In Angular 17, a ton of great features were introduced, and one of great importance is the new block template syntax, known as @-syntax notation, which led to the introduction of a few new APIs in the template.

These APIs further extend the template's HTML syntax, with the one standing out amongst them, known as Deferrable Views, accessible through the @defer block.

Currently in developer preview, Deferrable Views, augment the Angular templates with a declarative, built-in mechanism, that allows us, developers, to specify which template portions - components, directives, pipes, and any associated CSS - to be lazily loaded later when needed.

In this article, I will not do an in-depth guide to Deferrable Views but I want to show the manual work that the Angular team took away from us, developers, and moved to the framework itself thus allowing us to achieve lazy loading benefits through a declarative template syntax.

For the showcase, I am going to demo the most often use-case I used to do lazy loading: below-the-fold content, that will be loaded and rendered when in viewport.

Showcase requirements

To better understand what we want to showcase here, let's first define the points we want to implement, as the following:

Trigger lazy loading when in the viewport.
Handle the loading and error state accordingly.
Handle the flickering issue.

Those represent the main, basic points for our showcase, and later afterward we can implement more complex points like:

Early triggering of lazy loading using another trigger element.
Lazy loading of multiple template portions (read: components).

Let's dive in 🚀

Classic Template-Level Lazy Loading

Before Angular 17, there were existing imperative APIs that made it possible to create template portions dynamically - components, directives, pipes, and any associated CSS - and were closely similar to the way how Angular internally handles component creation, and manages templates and views. The dependencies planned to be lazily loaded did not need to be present in the template, and we heavily relied on the imperative usage of JavaScript's dynamic imports to asynchronously load their corresponding modules at runtime.

An advantage of these classic APIs is that you could take different ways of doing lazy loading, so what I will show here is maybe the simplest way of doing it.

The sample demo 🐱‍🏍

As a starting point, let's use the UserProfile component below:

@Component({
  ...
  template: `
    <div class="wrapper">
      <app-details></app-details>
    </div>

    <div class="wrapper wrapper-xl">
      <app-projects></app-projects>
      <app-achievements></app-achievements>
    </div>

    ...
  `,
  imports: [ProjectsComponent, AchievementsComponent]
  ...
})
export class UserProfileComponent {}

The Details component shows a pretty long description of the user, meanwhile, the Projects and Achievements components render the list of projects and achievements. As a result of the description being very long, those two components are not visible initially to the user, they are out of the viewport 👇:

This kind of content is known as below-the-fold content, and it's a perfect candidate for lazy loading when working toward improving the initial page load and application bundle.

Initially, we will lazy load only the Projects component, and be sure to fulfill the main, basic points we defined above. By using classic APIs, here's how the template would initially look like:

type DepsLoadingState = 'NOT_STARTED' | 'IN_PROGRESS' | 'COMPLETE' | 'FAILED';

@Component({
  ...
  template: `
    <div class="wrapper">
      <app-details></app-details>
    </div>

    <div class="wrapper wrapper-xl">
      <ng-template #contentSlot /> // 👈 insert lazily loaded content here 

      <ng-container *ngIf="depsState$ | async as state">
        <ng-template *ngIf="state == 'IN_PROGRESS'" [ngTemplateOutlet]="loadingTpl"></ng-template>
        <ng-template *ngIf="state == 'FAILED'" [ngTemplateOutlet]="errorTpl"></ng-template>
      </ng-container>

      <ng-template #loadingTpl>
        <app-projects-skeleton />
      </ng-template>

      <ng-template #errorTpl>
        <p>Oops, something went wrong!</p>
      </ng-template>
    </div>
    ...
  `,
  imports: [] // 👈 no need to import
  ...
})
export class UserProfileComponent {
  depsState$ = new BehaviorSubject<DepsLoadingState>('NOT_STARTED');
}

As you can see, components are removed from the template, and not imported in the imports array of component's or NgModule's metadata. Then, we defined the container or slot (template ref #contentSlot) in the template (using ng-template) where the lazily loaded content will be inserted.

Besides these, we have also defined the loading, and error templates (again, using ng-template) to help mirror the state of the loading dependencies (tracked by depsState$ subject) into the template.

but 🤚… initially, nothing happens, as no code triggers the loading process …😕

To fulfill the first point - start loading when in the viewport - we need to define a trigger which is nothing more than the action that needs to occur for the loading of template dependencies to start. In our case, we want to show the content when in the viewport (trigger action) but with the initial template, the content is not present. So, we have to define what is going to trigger that action.

The placeholder template for the rescue 💪

To have some initial content there in the view, let's add a temporary template, that when in the viewport, triggers the loading of desired content. This temporary template is known as a placeholder template 👇:

...
template: `
  ...
  <ng-container *ngIf="depsState$ | async as state">
        <ng-template *ngIf="state == 'NOT_STARTED'" 
          [ngTemplateOutlet]="placeholderTpl">
        </ng-template>
        ...
  </ng-container>

  <ng-template #placeholderTpl>
    <p>Projects List will be rendered here...</p> // 👈 trigger element
  </ng-template>
  ...
`
...

The placeholder template, also known as the trigger element is defined as a ng-template because it will be removed after it fires the loading of template dependencies, the Project component in our case.

Now with the trigger element in place, all that is left is to define the trigger itself which fires the loading when the trigger element (placeholder) enters the viewport.

For this purpose, we are going to use the IntersectionObserver Web API. We encapsulate the logic in a directive, which emits an event whenever the element it is applied on (trigger element) enters the viewport and stops tracking/observing the trigger element afterward, as below 👇:

@Directive({
    selector: '[inViewport]',
    standalone: true
})
export class InViewportDirective implements AfterViewInit, OnDestroy {
    private elRef = inject(ElementRef);

    @Output()
    inViewport: EventEmitter<void> = new EventEmitter();

    private observer!: IntersectionObserver;

    ngAfterViewInit() {
        this.observer = new IntersectionObserver((entries) => {
            const entry = entries[entries.length - 1];
            if (entry.isIntersecting) {
                this.inViewport.emit();
                this.observer.disconnect();
            }
        });

        this.observer.observe(this.elRef.nativeElement)
    }

    ngOnDestroy(): void {
        this.observer.disconnect();
    }
}

Once emitting, it is in the UserProfile component to take care of the loading process next:

@Component({
  ...
  template: `
    ...
    <div class="wrapper wrapper-xl">
      ...
      <ng-template #placeholderTpl>
        // 👇 apply directive to the trigger element
        <p (inViewport)="onViewport()">
            Projects List will be rendered here...
        </p> 
      </ng-template>
      ...
    </div>
    ...
  `,
  imports: [InViewportDirective]
  ...
})
export class UserProfileComponent {
  @ViewChild('contentSlot', { read: ViewContainerRef }) 
  contentSlot!: ViewContainerRef;

  depsState$ = new BehaviorSubject<DepsLoadingState>('NOT_STARTED');

  onViewport() {
    this.depsState$.next('IN_PROGRESS');

    const loadingDep = import("./user/projects/projects.component");
    loadingDep.then(
      c => {
        this.contentSlot.createComponent(c.ProjectsComponent);
        this.depsState$.next('COMPLETE');
      },
      err => this.depsState$.next('FAILED')
    )
  }
}

To asynchronously load the component, we use JavaScript's dynamic import function, and then update the tracking state following the state of the loading process thus properly mirroring the state in the template too. Since the loading logic is in the component class, we have to query the container/slot in the template and then use it to instantiate and insert the host of the loaded component into the container after it has been loaded, as you can see below 👇:

And … that's great! We have a working solution. But if you look carefully, one can observe that the Project component is loaded but the placeholder is hardly visible, and the loading template is not rendered at all because projects are rendered. This can happen if the dependencies are loaded quickly, thus implying some sort of flickering when loading is ongoing.

This leads us to the 3rd main point we defined above, and this can be resolved by coordinating the time when the placeholder and loading template render, as below:

function delay(timing: number) {
  return new Promise<void>(res => {
    setTimeout(() => {
      res()
    }, timing);
  })
}

@Component({...})
export class UserProfileComponent {
  @ViewChild('contentSlot', { read: ViewContainerRef }) 
  contentSlot!: ViewContainerRef;

  depsState$ = new BehaviorSubject<DepsLoadingState>('NOT_STARTED');

  onViewport() {
    // time after the loading template will be rendered
    delay(1000).then(() => this.depsState$.next('IN_PROGRESS'));

    const loadingDep = import("./user/projects/projects.component");
    loadingDep.then(
      c => {
        // minimum time to keep the loading template rendered
        delay(3000).then(() => {
          this.contentSlot.createComponent(c.ProjectsComponent);

          this.depsState$.next('COMPLETE')
        });
      },
      err => this.depsState$.next('FAILED')
    )
  }
}

Thus ensuring users a better visual indication of what is happening and a smoother experience 🤗:

We have fulfilled all of the 3 main points we planned to showcase. A complex one but often, a common requirement, is when we want the loading to start a little bit earlier - before the user scrolling makes the placeholder enter the viewport. This means that the trigger element is different from the placeholder template, and another element above in the template has to be used for that purpose, see below:

@Component({
  ...
  template: `
     ...
    // 👇 trigger element somewhere above in the template
    <span (inViewport)="onViewport()"></span>

    <div class="wrapper wrapper-xl">
      <ng-template #contentSlot /> // 

      <ng-container *ngIf="depsState$ | async as state">
        <ng-template *ngIf="state == 'NOT_STARTED'" [ngTemplateOutlet]="placeholderTpl"></ng-template>
        <ng-template *ngIf="state == 'IN_PROGRESS'" [ngTemplateOutlet]="loadingTpl"></ng-template>
        <ng-template *ngIf="state == 'FAILED'" [ngTemplateOutlet]="errorTpl"></ng-template>
      </ng-container>

      <ng-template #placeholderTpl>
        <p>Projects List will be rendered here...</p>
      </ng-template>
      ...
    </div>
    ...
  `,
  imports: [InViewportDirective]
  ...
})
export class UserProfileComponent {
  ...
  onViewport() {
    // same implementation as above
  }
}

Now, while the user scrolls down and the trigger element (span) enters the viewport, the loading of dependencies starts, see below:

That is easily verified, as you can see the loading message in the view when scrolling to the Projects section of the page. That's great 😎.

Lazy loading of multiple components

The code we wrote is imperative and simple, but we have one last point to fulfill: to lazy load more than one component. To showcase, the Achievements component is ready to be loaded alongside the Projects component.

There are 2 paths we can follow for this case: either load them separately or together. If we decide to follow the former option, the same work needs to be done as we did for the Products component, and to be fair even though it is simple, it is a pretty amount of work 😁.

If decide to follow the latter option, little to no changes are required - you need to adjust the loading and placeholder template to reflect the load of both components and adjust the loading logic in the components' class to manage both dependencies. Notice the use of Promise.AllSettled static method to handle the dynamic loading of multiple dependencies:

function loadDeps() {
  return Promise.allSettled(
    [
      import("./user/projects/projects.component"),
      import("./user/achievements/achievements.component")
    ]
  );
}

@Component({
  template: `
    <div class="wrapper wrapper-xl">
      <ng-template #contentSlot />

      <ng-template #placeholderTpl>
        <p (inViewport)="onViewport()">
            Projects and Achievements will be rendered here...
        </p>
      </ng-template>

      <ng-template #loadingTpl>
        <h2>Projects</h2>
        <app-projects-skeleton />

        <h2>Achievements</h2>
        <app-achievements-skeleton />
      </ng-template>
      ...
    </div>
  `,
})
export class UserProfileComponent {
  ...
  async onViewport() {
    await delay(1000);
    this.depsState$.next('IN_PROGRESS');

    const [projectsLoadModule, achievementsLoadModule] = await loadDeps();
    if (projectsLoadModule.status == "rejected" || achievementsLoadModule.status == "rejected") {
      this.depsState$.next('FAILED');
      return;
    }

    await delay(3000);

    this.contentSlot.createComponent(projectsLoadModule.value.ProjectsComponent);
    this.contentSlot.createComponent(achievementsLoadModule.value.AchievementsComponent);

    this.depsState$.next('COMPLETE');
  }
}

As you can see, we are still using the same template container/slot for inserting the components into the view, so as a result, we get this 👇:

Error handling of dependencies is project-specific and you are free to implement it as you think it works better for you.

This is all for the classic approach, a considerable amount of work isn't it? Now let's explore the modern approach.

Modern Template-Level Lazy Loading: Deferrable Views

Now, let's see how this new, modern API fits our showcase. For consistency's sake, we will use the same UserProfile component, thus having a close comparison with the classic APIs. As the article's introductory section notes, Angular 17 introduced Deferrable Views, a new API that moves the burden of classic APIs from developers to the framework - more specifically, the compiler.

Remembering the base points defined above, all that is needed to achieve the same result is the following template code 👇:

@Component({
  ...
  imports: [... ProjectsComponent],
  template: `
    <div class="wrapper">
       <app-details />
    </div>

    <div class="wrapper wrapper-xl">
       @defer (on viewport) {
         <app-projects />
       } @placeholder {
         <p>Projects will be rendered here...</p>
       } @loading {
          <app-projects-skeleton />
       } @error {
          <p>Oops, something went wrong!</p>
       }
    </div>
  `
})
export class UserProfileComponent {}

Can you notice the template-driven approach? There is no imperative work for state management and async loading, thus having a code-free class component. The content to be lazy-loaded is specified inside the @defer block and the trigger is defined as a parameter after that (on viewport). Also, you declaratively define the placeholder, error, and loading templates using the naming-relevant template @blocks (no ng-templates) to properly mirror the state of the process in the template, with the placeholder template being the trigger element:

But there is a small detail that you may have spotted already: since the Project component is on the template at the author's time, it needs to be imported into the imports array of the component's metadata just so template dependencies are detectable and reachable. But, the compiler is aware of that, so everything works as it should.

You may also notice the flickering issue occurring for the same reasons as before. As earlier, to fix it, you need to coordinate the time when either the placeholder or loading template is shown. To accomplish this, the @loading block accepts two optional params, minimum and after, as below:

@Component({
  ...
  template: `
    ...
    <div class="wrapper wrapper-xl">
       @loading (after 1s; minimum 3s) {
          <app-projects-skeleton />
       }
    </div>
    ...
  `
})
export class UserProfileComponent {}

The parameters provided to the @loading block control when and how long it should be rendered on the view. In our case, parameters specify that the @loading block is to be shown one second after the loading process begins and remain visible for at least three seconds:

The deferrable views work only with standalone dependencies.

Triggers themselves are capable of accepting parameters, just like template blocks do. In our scenario, the viewport trigger accepts an optional parameter which is a DOM element that acts as the trigger element ( replacing the placeholder template). This enables dependencies to begin loading before the user scrolls to the area of the page where the loaded content will be rendered:

@Component({
  ...
  imports: [ProjectsComponent],
  template: `
    ...
    <span #triggerEl></span>
    ...

    <div class="wrapper wrapper-xl">
       @defer (on viewport(triggerEl)) {
         <app-projects />
       } 
       ...
    </div>
  `
})
export class UserProfileComponent {}

The loading of dependencies now begins as the user scrolls down and the trigger element (span) reaches the viewport, see below 👇:

That is easily verified, as you can see the loading template in the view when scrolling to the Projects section of the page. That's great 😎.

Lazy loading of multiple components

Up to now, we still have one last point to fulfill: lazy loading more than one component. To showcase, the Achievements component is ready to be loaded alongside the Projects component.

As with the classic approach, there are 2 paths to follow: either load them separately or together. With the new API, @defer block, both of these options are easy to implement 😎.

Loading them together 🚀

To load components together, the Achievements component needs to be imported to the imports array of component metadata, and then inserted into the @defer block, as below:

@Component({
  ...
  imports: [... ProjectsComponent, AchievementsComponent],
  template: `
     ...

    <div class="wrapper wrapper-xl">
       @defer (on viewport) {
         <app-projects />
         <app-achievements />
       } @placeholder () {
         <p>Projects and Achievements will be rendered here...</p>
       } @loading (after 1s; minimum 3s) {
          <h2>Projects</h2>
          <app-projects-skeleton />

          <h2>Achievements</h2>
          <app-achievements-skeleton />
       } @error {
          <p>Oops, something went wrong!</p>
       }
    </div>
  `
})
export class UserProfileComponent {}

Also, the loading and placeholder templates are adjusted to reflect the loading of both components and nothing anymore👇:

Loading them separately 🚀

To load components separately, each of them should be wrapped in its @defer block and define other associated blocks:

@Component({
  ...
  imports: [... ProjectsComponent, AchievementsComponent],
  template: `
     ...

    <div class="wrapper wrapper-xl">
       @defer (on viewport) {
          <app-projects  />
       } @placeholder () {
          <p>Projects will be rendered here...</p>
       } @loading (after 1s; minimum 3s) {
          <h2>Projects</h2>
          <app-projects-skeleton />
       } @error {
          <p>Oops, something went wrong!</p>
       }

       @defer (on viewport) {
          <app-achievements />
       } @placeholder () {
          <p>Achievements will be rendered here...</p>
       } @loading (after 1s; minimum 3s) {
          <h2>Achievements</h2>
          <app-achievements-skeleton />
       } @error {
          <p>Oops, something went wrong!</p>
       }
    </div>
  `
})
export class UserProfileComponent {}

Compared with the classic approach, far less code is required. You can add as many @defer blocks as you need with little effort, and still be sure that it works perfectly fine 🤗:

That's all for the modern approach. These are only a handful of the many features that Deferrable View offers. Check out these resources for a more comprehensive guide on deferrable views:

Angular Deferrable Views Docs.
Article and Video: Tomas Trajan, Matthieu Riegler, Fanis Prodromou

Conclusion

Lazy loading is a performance optimization technique adopted in web frameworks like Angular. Route-level lazy loading is very popular in the Angular community but template-level lazy loading is lacking popularity even though time has proven that existing APIs work very well. The amount of work, involvement of both component's class and template, and all of that imperative code makes them everything but not developer-friendly.

Angular 17, through the @block template syntax, deferrable views provide a modern, declarative, template-driven API, that can be used to defer the loading of portions of the template that may not ever be loaded until a future point in time. All you need to do is determine which setup of these APIs best suits your intended use case.

You can find and play with the final code here: https://github.com/ilirbeqirii/lazy-load-component

Special thanks to @kreuzerk and @eneajaho for review.

Thanks for reading!

I hope you enjoyed it 🙌. If you liked the article please feel free to share it with your friends and colleagues.
For any questions or suggestions, feel free to comment below 👇.
If this article is interesting and useful to you, and you don't want to miss future articles, follow me at @lilbeqiri, dev.to, or Medium. 📖

Local Change Detection in Angular 17

Ilir Beqiri — Fri, 22 Dec 2023 17:07:23 +0000

How to use Angular Signals and OnPush change detection strategy to improve performance with local change detection

For quite some time now, the Angular community has been witnessing a lot of improvements and new features being added to their beloved framework. A few weeks ago, Angular v17 was released introducing a ton of high-quality improvements and features, with signals APIs (except effect()) making their way out of developer preview. With performance always being the discussion topic in the community regarding change detection, stable signal APIs seem to make the framework more powerful and smarter in change detection 🤯.

You can read more about Angular v17 in the official blog post.

Some time ago, the Angular team started working on finding a way to introduce locality awareness in the framework (when detecting changes) in the sense of figuring out what impact a change of state has on the application thus not depending on Zone.js anymore.

For this purpose, in Angular v17, conforming to the current Zonejs-based, top-down change detection approach, signals have been fine-tuned, providing a starting point toward locality awareness, thus introducing some sort of what the Angular community calls Local Change Detection 🚀.

This is a great ability that has been added to the framework through signals and is expected to provide performance gains, but is this what the community has been thriving for? is this going to reduce the amount of checks needed during a change detection cycle? and is it somehow related to change detection strategies?

In this article, we are going to elaborate and see how that locality awareness is achieved, conditions for it to be used effectively and properly, and show some working examples. Let's dive in 🐱‍🏍.

Change Detection Modes

Before Angular v17, whenever an event happens that Zone.js is patching, which may lead to state changes, Zone.js picks up this event and informs Angular that some state changed (not specifically where) and that it should run change detection. Since Angular does not know where a change comes from or where the change happened, it starts traversing the component tree and dirty-checking the all components. This approach to detect changes is known as the Global mode.

With signals🚦, this approach is going to be fine-tuned in the sense that no need to dirty-check all the components anymore. Signals can track where they are being consumed. For signals bound on the component template, the template is a consumer, that every time the signal value changes, needs to pull out that new value (hence live consumer). Thus when signal value changes, it is enough to mark its consumers as dirty, but not need the same for ancestor components (as it was pre-v17). For this purpose, a new improvement shipped in the latest version makes signals smart enough to mark dirty only that specific component it is consumed on (live consumer) and marks ancestor components for traversal (by adding the HasChildViewsToRefresh flag).

To achieve this, a new function markAncestorsForTraversal is introduced replacing markViewDirty (which is used to mark dirty also all ancestor components). Let's look at the underlying code:

export function consumerMarkDirty(node: ReactiveNode): void {
  node.dirty = true;
  producerNotifyConsumers(node);
  node.consumerMarkedDirty?.(node);
}

consumerMarkedDirty: (node: ReactiveLViewConsumer) => {
  markAncestorsForTraversal(node.lView!);
},

export function markAncestorsForTraversal(lView: LView) {
  let parent = lView[PARENT];
  while (parent !== null) {
    // We stop adding markers to the ancestors once we reach one that already has the marker. This
    // is to avoid needlessly traversing all the way to the root when the marker already exists.
    if ((isLContainer(parent) && (parent[FLAGS] & LContainerFlags.HasChildViewsToRefresh) ||
         (isLView(parent) && parent[FLAGS] & LViewFlags.HasChildViewsToRefresh))) {
      break;
    }

    if (isLContainer(parent)) {
      parent[FLAGS] |= LContainerFlags.HasChildViewsToRefresh;
    } else {
      parent[FLAGS] |= LViewFlags.HasChildViewsToRefresh;
      if (!viewAttachedToChangeDetector(parent)) {
        break;
      }
    }
    parent = parent[PARENT];
  }
}

During change detection (triggered by Zone.js), components marked for traversal, when visited, let Angular understand that they don't need to be checked for changes but that they have dirty children. This way ensures they are accessible during the change detection process even when they are not dirty but skipped on the way to the dirty children which are refreshed. As a result, the new ability of signals to localize where in the component tree the change has occurred provides the "Local" change detection we talked about earlier. The improved approach enforced by signals is known as the Targeted mode of detecting changes. In this mode, Angular still initiates a top-bottom checking process (recall triggered by Zone.js), but now it traverses through components marked for traversal, and targets to refresh only dirty consumers.

This approach certainly seems to bring performance gains in overall application but do we have it out of the box or is it an opt-in feature?

Change Detection Strategies

In general, the best way to address performance concerns is by doing less work, which means, running less code, and in Angular, this means reducing change detection cycles and the number of components being checked for changes during a cycle. To achieve this, Angular needs a way to know which components must or not be checked for changes.

Since Angular is not able to know exactly which component has changed, and change detection is global, the top-bottom process, assumes that all components in the tree are dirty, and need to be checked for changes on every cycle. This means that components, dirty or not, will be checked for changes. This behavior and conformance of components regarding the change detection process is referred to as a change detection strategy. Since this is the default component behavior, it is known as the Default change detection strategy.

To improve this behavior, and make Angular do less work, the Angular team introduced a new strategy that reduces the number of components to be checked for changes. This new strategy is known as the OnPush change detection strategy, which allows skipping subtrees of components that are not dirty.

There are 3 criteria when the OnPush component is marked dirty, and you can find more about them in this article.

Now, based on this information, we can allude that the OnPush change detection strategy seems to let us benefit from v17's Local change detection. Let's find out if it stands 💪.

Hybrid Change Detection

For demo purposes, below is a small reproduction of the app supporting our case:

@Component({
  ...
  selector: 'app-child-y',
  templateUrl: `
    <div class="container">
      <h3>Child Y<br /> value: {{ count() }} runs: {{getChecked()}}</h3>

      <app-grandchild-y />
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  ...
})
export class ChildYComponent {...}

@Component({
  ...
  selector: 'app-child-x',
  templateUrl: `
    <div class="container">
      <h3>Child X <br /> value: {{ count() }} runs: {{getChecked()}}</h3>

      <app-grandchild-x />
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  ...
})
export class ChildXComponent {...}

@Component({
  ...
  selector: 'app-parent',
  templateUrl: `
    <div class="container">
      <h2>Parent <br /> value: {{count()}} runs: {{getChecked()}}</h2>

      <div class="children">
        <app-child-x />
        <app-child-y />
      </div>
    </div>
  `,
  ...
})
export class ParentComponent {...}

The app visualizes a component tree, with the Parent component having Default change detection, and its two child components, ChildX and ChildY components, each with OnPush change detection, and one child component, GrandChildX component and GrandChildY component respectively, as below:

@Component({
  ...
  selector: 'app-grandchild-x',
  templateUrl: `
    <div class="container">
      <h4>(GrandChild X <br /> value: {{ count() }} runs: {{getChecked()}}</h4>

      <button (click)="updateValue()">Increment Count</button>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  ...
})
export class GrandchildXComponent {
  ...

  updateValue() {
    this.count.update((v) => v + 1);
  }
}

@Component({
  ...
  selector: 'app-grandchild-y',
  templateUrl: `
    <div class="container" appColor>
      <h4>(GrandChild Y <br /> value: {{ count() }} runs: {{getChecked()}}</h4>

      <button #incCount>Increment Count</button>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  ...
})
export class GrandchildYComponent implements AfterViewInit {
  ...

  @ViewChild('incCount') incButton!: ElementRef<HTMLButtonElement>;

  ngZone = inject(NgZone);
  injector = inject(Injector);
  app = inject(ApplicationRef);

  ngAfterViewInit(): void {
    runInInjectionContext(this.injector, () => {
      this.ngZone.runOutsideAngular(() => {
        fromEvent(this.incButton.nativeElement, 'click')
          .pipe(throttleTime(1000), takeUntilDestroyed())
          .subscribe(() => {
            this.count.update((v) => v + 1);
            this.app.tick();   
          });
      });
    });
  }
}

The only difference between grandchild components is the way the click event handler is handled. In the following section, we will understand the reason behind this decision.

Now that on both sides of the component tree, all components are using the OnPush strategy, let's check what happens when incrementing the count at the GrandChildX component:

What we are witnessing here is no difference as if it was a Global strategy in use. Even though components use the OnPush strategy they are still being checked for changes. Why is this happening?

Well, Angular internally wraps event listeners in a function that marks the component and its ancestors for check when an event happens. In addition, Zone.js monkey-patches the event and notifies Angular when it's fired so that Angular can start change detection. So in our case, when we click the button, it marks current and ancestor components as dirty. And since change detection starts in Global mode, the whole tree is refreshed. This is how change detection used to work before v17 and was left intact for backward compatibility purposes.

Based on this, we can conclude that to get Local CD benefits, we have to: update the signal in a way that doesn't mark for checking all the ancestor components.

Hmm🤔… okay. We took care of the increment button at the GrandChildY component to respect this requirement (credits Thomas Laforge), so let's see what we get now 👇:

And yay 😊. Now we get the local change detection in our application. To be more clear, when the button is clicked, the signal value gets updated, which then marks the current component(consumer) as dirty and the ancestor components for traversal. After that, Zone.js gets triggered (remember monkey-patching) which notifies Angular, then Angular starts change detection in Global mode and refreshes the Parent component because it uses the Default change detection strategy, switches to the Targeted mode when visiting components marked for traversal (with the HasChildViewsToRefresh flag), and uses the OnPush change detection strategy, ChildY component in this case, traversing them but not refreshing, then finally coming to the dirty GrandChildY component (consumer), switching back to the Global mode of change detection, and refreshing the view. This back-and-forth switching that Angular does between change detection modes, Global and Targeted, is known as Hybrid change detection 🐱‍🏍.

If you want to see how this is managed internally, check the source code at Angular repo.

Now, with all of those things mentioned, someone can say that there seem to be not too many places where we would get the benefits of local change detection. Indeed, we won't get the benefit all over the place, but also the click handling above is not the usual thing we do a lot. But there are other use cases where we can get this benefit (credits Enea Jahollari), see below:

Here you can see a more usual case, where you have some shared state in service, a typical case being state management libraries (NgRx, Akita, …), and that piece of state is being used in many components throughout the component tree. Also, the case of having some state on the parent component that can be consumed from child components. When this state (remember a signal value ⚠) changes, only the components that consume (consumers) the state are marked dirty, and with the OnPush CD strategy set on, you will get the benefits of local change detection.

This is a typical use case to mention and, if you have in mind other use cases where we can benefit from local change detection, feel free to share them with me and the community.

Conclusion

Improving change detection has always been one of the priorities of the Angular team and community. This kind of locality that we have now in v17 is not the complete one but it represents a good start and initial step toward what is expected to be delivered on future versions. Even though not provided out of the box, developers can leverage local change detection benefits in their apps with a few adjustments: OnPush change detection strategy and Signals. To know more what's the Angular team's plan regarding reactivity, check the released roadmap 🔥.

Here is a visualization of all that was presented in the article:

You can find and play with the final code here: https://stackblitz.com/edit/local-cd-angular-17?file=src%2Fmain.ts

Additional Resources

If you want to read more about local change detection in v17 make sure you check these resources.

Special thanks to @kreuzerk, @eneajaho, @tomastrajan, and Matthieu Riegler for review.

Thanks for reading!

Declarative Loop Control Flow in Angular 17

Ilir Beqiri — Fri, 20 Oct 2023 18:01:43 +0000

In the last few releases, a relatively short time, we witnessed a lot of additions and improvements to the Angular framework, and the future seems to be no worse. Angular Renaissance or Momentum, the next version (v17) will come with some more high qualitative improvements, one amongst them being the new built-in Control Flow Template Syntax.

As the name suggests, this improvement, introduces the built-in control flow for templates, a new declarative syntax of writing control flow in the template, thus providing the functionality of *ngIf *ngFor, and *ngSwitch (directive-based control flow) into the framework itself.

The template syntax has been debated for some time, with the Angular team and community providing their solutions, and after careful reasoning and their trust in the community, the @-syntax (community proposal) was chosen to back the template control flow.

You can read more about it (reason, benefits, implications … etc) in the Angular RFC: Built-in Control Flow and template syntax choice in the Angular blog post.

Loop control flow @-for, is what grabbed my attention the most, because of the new supporting @-empty block that shows a template when no items are in the list:

@for (product of products; track product.title) {
  <tr>
    <td>{{ product.title }}</td>
    <td>{{ product.description }}</td>
    <td>{{ product.price }}</td>
    <td>{{ product.brand }}</td>
    <td>{{ product.category }}</td>
  </tr>
} @empty {
  <p>No products added yet!</p>
}

This new template syntax allows removing all the ng-container and ng-template elements on the template that supported *ngIf and *ngFor making templates more compact and offering a better user experience.

In this article, I want to show how a for loop code looks now in the template after using built-in control flow syntax, and a misconception I created for the @-empty block when iterating over data loaded asynchronously (observable results, or read-only signal values from the toSignal function). Let's dive into an example!

Hands-on! 🐱‍🏍

This demo will have a Products component that renders a list of products into a table. Below you see the iteration being done using the current *ngFor structural directive:

import { Component, inject } from '@angular/core';
import { AsyncPipe, CommonModule } from '@angular/common';
import { ProductService } from '../product.service';

@Component({
  selector: 'app-products',
  standalone: true,
  imports: [CommonModule, AsyncPipe],
  template: `
    <table>
      <thead>
        <tr>
          <th>Title</th>
          <th>Description</th>
          <th>Price</th>
          <th>Brand</th>
          <th>Category</th>
        </tr>
      </thead>

      <tbody>
        <ng-container *ngIf="products$ | async as products">
          <ng-container *ngIf="products.length; else noResults">
            <tr *ngFor="let product of products">
              <td>{{ product.title }}</td>
              <td>{{ product.description }}</td>
              <td>{{ product.price }}</td>
              <td>{{ product.brand }}</td>
              <td>{{ product.category }}</td>
            </tr>
          </ng-container>

          <ng-template #noResults>
            <p>No results yet!</p>
          </ng-template>
        </ng-container>
      </tbody>
    </table>
  `,
  styleUrls: ['./products.component.scss'],
})
export class ProductsComponent {
  products$ = inject(ProductService).getProducts(); 
}

You can see the ng-template | ng-container elements used, we first check for a null case, guarding against the initial null value emitted from the async pipe, making sure we get the result from the products observable when emitted, and then check if the list is empty to render the default message or render the products in the table.

Now you correctly ask, what would it look like with the new @-for control flow 🤔?

Look at this code 😍:

...

@Component({
  ...
  template: `
    <table>
      ...

      <tbody>
        @if (products$ | async; as products) {
          @for (product of products; track product.title) {
           <tr>
             <td>{{ product.title }}</td>
             <td>{{ product.description }}</td>
             <td>{{ product.price }}</td>
             <td>{{ product.brand }}</td>
             <td>{{ product.category }}</td>
           </tr>
          } @empty {
           <p>No results yet!</p>
          }
        }
      </tbody>
    </table>
  `,
  ...,
})
export class ProductsComponent {
  products$ = inject(ProductService).getProducts(); 
}

No ng-container | ng-template elements are present. It is the new @-for and @-empty in combination that removes the need to check if the products list is empty and what template to render based on that, default message or products table hence no more "imperative" check.

And it's the @-if block that does the check for the null value emitted from the async pipe. Also, the new syntax enforces the use of track, a function that improves performance. Thus we have less, cleaner code, more performant, and easy to understand, read, and write.

My misconception for @-empty block 😁

When I first started experimenting with the new Control Flow, I was expecting the @-empty block in combination with @-for block to be working under the hood like for await of statement in JavaScript - in the sense that if the data to be iterated loads asynchronously as the result of an observable or a read-only signal created by toSignal function, it would wait until the data is loaded and then decide if the @-empty block renders or not.

In short, I thought we did not need to check for a null value when waiting for an observable to emit:

...

@Component({
  ...
  template: `
    <table>
      ...
      <tbody>
        // no @if check here...
        @for (product of products$ | async; track product.title) {
          <tr>
            <td>{{ product.title }}</td>
            <td>{{ product.description }}</td>
            <td>{{ product.price }}</td>
            <td>{{ product.brand }}</td>
            <td>{{ product.category }}</td>
          </tr>
        } @empty {
          <p>No results yet!</p>
        }
      </tbody>
    </table>
  `,
  ...,
})
export class ProductsComponent {
  products$ = inject(ProductService).getProducts(); 
}

or when reading from a read-only signal:

...

@Component({
  ...
  template: `
    <table>
      ...
      <tbody>
        // no @if check here...
        @for (product of products(); track product.title) {
          <tr>
            <td>{{ product.title }}</td>
            <td>{{ product.description }}</td>
            <td>{{ product.price }}</td>
            <td>{{ product.brand }}</td>
            <td>{{ product.category }}</td>
          </tr>
        } @empty {
          <p>No results yet!</p>
        }
      </tbody>
    </table>
  `,
  ...,
})
export class ProductsComponent {
  products = toSignal(this.productService.getProducts(), { initialValue: null });
}

But just like the if/else statement of any programming language that works on a sync sequence of values, the same stands for the @-for control flow in templates.

What happens in this case, is that first the @-empty block with the "No results yet!" message is rendered, and then after the data comes from the server, the products table is rendered:

During the time RFC was open for review, I left a comment asking if an optional condition could be added to the @-empty block ({: empty} at the time of comment was left) to make it able to wait until data is loaded. The Angular team cares about its community and takes into consideration their input, and it may do something for this behavior in the near future.

FYI: Angular v17 is officially in a release candidate phase now. Feel free to grab and experience its new features.

Special thanks to @kreuzerk , @danielglejzner and @eugenioz

Thanks for reading!

I hope you enjoyed it 🙌. If you liked the article please feel free to share it with your friends and colleagues.

For any questions or suggestions, feel free to comment below 👇.

If this article is interesting and useful to you, and you don't want to miss future articles, follow me at @lilbeqiri, dev.to, or Medium. 📖

Should You Pair Signals & OnPush?

Ilir Beqiri — Thu, 21 Sep 2023 16:56:09 +0000

When building a web application, there are different aspects that we take into consideration, performance being one of them. Especially when working on a considerable Angular codebase, there is always space for performance improvements.

An inherited codebase is what I have been working on recently, and the main thing to be improved was the performance of the application — refactoring to libraries, smart and dumb components, and starting to utilize the OnPush change detection strategy amongst other improvements.

In this article, I want to share the issue we faced while sparingly adding the OnPush strategy to components. Additionally, I will elaborate on a few solutions that are already known that we can use, the latest one being the future, new reactive primitive, Angular Signals.

The OnPush Change Detection

Change Detection is the mechanism that makes sure that the application state is in sync with the UI. At a high level, Angular walks your components from top to bottom, looking for changes. The way it does, this is by comparing each current value of expressions in the template with the previous values they had using the strict equality comparison operator (===). This is known as dirty checking.

You can read more about in the official documentation.

Even though change detection is optimized and performant, in applications with large component trees, running change detection across the whole app too frequently may cause slowdowns and performance issues. This can be addressed by using the OnPush change detection strategy, which tells Angular to never run the change detection for a component unless:

At the time the component is created.
The component is dirty.

There are actually 3 criteria when OnPush CD runs, and you can find more about them in this article.

This allows to skip change detection in an entire component subtree.

The Problem:

To better understand the issue, below is a small reproduction of the app supporting our case:

@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule, RouterLink, RouterOutlet],
  template: `
    <h1>OnPush & Signals</h1>
    <a routerLink="/">Home</a> &nbsp;
    <a routerLink="/products">Products </a>
    <hr >

    <router-outlet></router-outlet>
  `,
})
export class AppComponent {
  name = 'OnPush & Signals';
}

bootstrapApplication(App, {
  providers: [
    provideHttpClient(),
    provideRouter([
      {
        path: '',
        component: HomeComponent,
      },
      {
        path: 'products',
        loadComponent: () =>
          import('./products-shell/products-shell.component'),
        children: [
          {
            path: '',
            loadChildren: () => import('./products').then((r) => r.routes),
          },
        ],
      },
    ]),
  ],
});

Using new standalone APIs in Angular, an application is bootstrapped with HttpClient and Router configured. The application has 2 routes configured, the default one for HomeComponent, and the 'products' for the Product feature (in our case being an Nx library) which is lazily-loaded when the route is activated and rendered in the lazily-loaded ProductShell component:

@Component({
  selector: 'app-products-shell',
  standalone: true,
  imports: [RouterOutlet],
  changeDetection: ChangeDetectionStrategy.OnPush, // configure OnPush
  template: `
    <header>
      <h2>Products List</h2>
    </header>

    <router-outlet></router-outlet>
  `,
  styleUrls: ['./products-shell.component.css'],
})
export default class ProductsShellComponent { }

The Product feature itself has the following route configuration:

export const routes: Routes = [
  {
    path: '',
    loadComponent: () => import('./products.component'),
    children: [
      {
        path: 'list',
        loadComponent: () => import('./products-list/products-list.component'),
      },
      {
        path: '',
        redirectTo: 'list',
        pathMatch: 'full',
      },
    ],
  },
];

Let’s first have a look at the way it should not be done, and then check the solutions:

Illustrating the problem

The ProductList component below calls the getProducts function inside the ngOnInit hook to get the list of products and then render it into a table.

@Component({
  selector: 'app-products-list',
  standalone: true,
  imports: [NgFor],
  template: `
    <table>
      <thead>
        <tr>
          <th>Title</th>
          <th>Description</th>
          <th>Price</th>
          <th>Brand</th>
          <th>Category</th>
        </tr>
      </thead>

      <tbody>
        <tr *ngFor="let product of products">
          <td>{{ product.title }}</td>
          <td>{{ product.description }}</td>
          <td>{{ product.price }}</td>
          <td>{{ product.brand }}</td>
          <td>{{ product.category }}</td>
        </tr>
      </tbody>
    </table>
  `,
  styleUrls: ['./products-list.component.css'],
})
export default class ProductsListComponent implements OnInit {
  products: Product[] =[];
  productService = inject(ProductsService);

  ngOnInit() {
    this.productService.getProducts().subscribe((products) => {
      this.products = products;
    });
  }
}

It will be rendered inside the Products component which wraps the <router-outlet> inside a div for page spacing purposes (in our case):

@Component({
  selector: 'app-products',
  standalone: true,
  imports: [RouterOutlet],
  template: `
   <div class="main-content">
    <router-outlet></router-outlet>
   </div>
  `,
  styles: [`.main-content { margin-top: 15px }`],
})
export default class ProductsComponent {}

At first sight, this code seems correct, but no products will be rendered on the table, and no errors in the console.

What could be happening? 🤯

This happens because of ProductShell (root) component is being configured using OnPushchange detection, and the "imperative way" of retrieving the products list. The products list is retrieved successfully, and the data model is changed, marking the ProductsList component as dirty, but not its ancestor components. Marking ProductShell OnPush skips all subtree of components from being checked for change unless it is marked dirty, hence data model change is not reflected on UI.
Now that we understand what the issue is, there are a few ways that can solve it. Of course, the easiest one is just reverting to the Default change detection and everything works. But let's see what are the other solutions out there:

Solution 1: Declarative Pattern with AsyncPipe

Instead of imperatively subscribing to the getProducts function in the component, we subscribe to it in the template by using the async pipe:

@Component({
  ...
  template: `
    <table>
      ...
      <tbody>
        <tr *ngFor="let product of products$ | async">
          <td>{{ product.title }}</td>
          <td>{{ product.description }}</td>
          <td>{{ product.price }}</td>
          <td>{{ product.brand }}</td>
          <td>{{ product.category }}</td>
        </tr>
      </tbody>
    </table>
  `
})
export default class ProductsListComponent {
  productService = inject(ProductsService);
  products$ = this.productService.getProducts();
}

The async pipe automatically subscribes to the observable returned by the getProducts function and returns the latest value it has emitted. When a new value is emitted, it marks the component to be checked for changes, including ancestor components (ProductShell is one of them in this case). Now, Angular will check for changes ProductShell component together with its component tree including the ProductList component, and thus UI will be updated with products rendered on a table:

Solution 2: Using Angular Signals 🚦

Signals, introduced in Angular v16 in the developer preview, represent a new reactivity model that tells the Angular about which data the UI cares about, and when that data changes thus easily keeping UI and data changes in sync. Together with the future Signal-Based components, will make possible fine-grained reactivity and change detection in Angular.

You can read more about Signals in the official documentation.

In its basics, a signal is a wrapper around a value that can notify interested consumers when that value changes. In this case, the ‘products’ data model will be a signal of the products which will be bound directly to the template and thus be tracked by Angular as that component’s dependency:

@Component({
  ...
  template: `
    <table>
      ...
      <tbody> <!-- getter function: read the signal value-->
        <tr *ngFor="let product of products()">
          <td>{{ product.title }}</td>
          <td>{{ product.description }}</td>
          <td>{{ product.price }}</td>
          <td>{{ product.brand }}</td>
          <td>{{ product.category }}</td>
        </tr>
      </tbody>
    </table>
  `
})
export default class ProductsListComponent implements OnInit {
  products = signal<Product[]>([]);
  productService = inject(ProductsService);

  ngOnInit() {
    this.productService.getProducts().subscribe((products) => {
      this.products.set(products);
    });
  }
}

When the 'products' signal gets a new value (through the setter function), being read directly on the template (through a getter function), Angular detects changed bindings, marking the ProductList component and all its ancestors' components as dirty / for change on the next change detection cycle.

Then, Angular will check for changes ProductShell component together with its component tree including the ProductList component, and thus UI will be updated with products rendered on a table:

The same solution can be achieved by following a declarative approach using the toSignal function:

@Component({
  selector: 'app-products-list',
  standalone: true,
  imports: [NgFor, AsyncPipe],
  template: `
    <table>
      …
        <tr *ngFor="let product of products()">
          <td>{{ product.title }}</td>
          <td>{{ product.description }}</td>
          <td>{{ product.price }}</td>
          <td>{{ product.brand }}</td>
          <td>{{ product.category }}</td>
        </tr>
      …
    </table>
  `
})
export default class ProductsListComponent implements OnInit {
  productService = inject(ProductsService);
  products: Signal<Product[]> = toSignal(this.productService.getProducts(), {
    initialValue: [],
  });
}

toSignal is a utility function provided by @angular/core.rxjs-interop (in developer preview) package to integrate signals with RxJs observables. It creates a signal which tracks the value of an Observable. It behaves similarly to the async pipe in templates, it marks the ProductList component and all its ancestors for change / dirty thus UI will be updated accordingly.

You can find and play with the final code here: https://stackblitz.com/edit/onpush-cd-deep-route?file=src/main.ts 🎮

Special thanks to @kreuzerk, @eneajaho, and @danielglejzner for review.

Thanks for reading!

This is my first article, and I hope you enjoyed it 🙌.

For any questions or suggestions, feel free to leave a comment below 👇.

If this article is interesting and useful to you, and don’t want to miss future articles, give me a follow at @lilbeqiri, Medium or dev.to. 📖