DEV Community: Jared Robertson

Lessons learned from Angular's control flow migration script

Jared Robertson — Fri, 06 Jun 2025 23:13:12 +0000

The old NgIf, NgFor, and NgSwitch directives are deprecated, and it's time to switch to the new control flow syntax @if, @for, and @switch. Angular's control flow migration script is really good, but it cannot correctly convert everything, so all changes must be manually checked.
My team has been hard at work with the conversion process. We have converted thousands of files, and only have about 150 files left. We have made many mistakes, and I hope that this article will help you avoid some of the pain we went through.

Do not run the script on your entire application

One huge pull request with all the changes is impossible to review, impossible to test, and you will ship regression bugs to your users.
I split our work up into tasks that each had fewer than 100 *ngIf statements in them. This worked as a starting point for a total time estimate. We have needed to split a few up into smaller tasks, and also combined some of them that were really small.

Avoid making non-script changes

A lot of our code is really old and was migrated from AngularJS, so there are plenty of clean-ups that we would like to do. As we started the conversion process, we would see all of these problems, and would ask the developer to make simple little fixes to clean things up. Do not fall into this trap. It is a very slippery slope.
Here are some of the "very small fixes" that turned into disasters.

Dangerous: Convert negated if-statements to if-else

In my opinion, the way to do an if-else statement with NgIf is difficult to read. Consequently, we would avoid using else statements, and would prefer doing something like this

<div *ngIf="loaded">
  ...
</div>
<div *ngIf="!loaded">Loading</div>

When the script runs, it will turn into this

@if (loaded) {
  <div>
    ...
  </div>
}
@if (!loaded) {
  <div>Loading</div>
}

It will be tempting to switch it to an else statement

@if (loaded) {
  <div>
    ...
  </div>
} @else {
  <div>Loading</div>
}

DO NOT DO THIS!!! While it may be fine 99% of the time, there will likely be confusing code blocks that aren't actually negated if-statements. For example, the following code would create an infinite loading message if there was an error.

@if (loaded && !error) {
  <div>
    ...
  </div>
}
@if (!loaded && !error) {
  <div>Loading</div>
}

This type of change is incredibly hard for reviewers and testers to catch. Just avoid it. You can fix it later.

Dangerous: Get rid of redundant div tags

A lot of our legacy code uses <div> tags that do nothing except hold the *ngIf directive (prefer <ng-container> instead).

After the conversion, the <div> will remain, look terrible, and you may want to just remove it.

<!-- Before conversion -->
<div *ngIf="condition">
  <div class="some-container">Contents</div>
</div>

<!-- After conversion -->
@if (condition) {
  <div><!-- Possibly unnecessary div -->
    <div class="some-container">Contents</div>
  </div>
}

Again, DO NOT DO THIS!!! While it may be fine 99% of the time, there will likely be some piece of CSS somewhere that depends on that unnecessary div, and could completely mess up the page.
Again, doing this is hard to review, hard to test, and it's much safer to keep all of them in.

Not as dangerous: Replace `let i = $index` with just `$index`

At the start, we had a huge list of additional things to change while we were going through the migration process. The only one we have kept is replacing let i = $index with just $index and similar changes.

These are much safer because the compiler can catch a lot of potential problems they really stick out when reviewing them. We also found a bunch of places where we were declaring i but weren't actually using it anywhere.

Inline elements will have spacing added

This was the most common problem for us that we needed to fix. A lot of our legacy code handles plurality in a very i18n-unfriendly way:

You have {{ count }} item<span *ngIf="count !== 1">s</span>.

Output:
> You have 1 item.
> You have 3 items.

After the migration, it will change to this

You have {{ count }} item
@if (count !== 1) {
  <span>s</span>
}
.

Output:
> You have 1 item .
> You have 3 item s .

Because we are operating on inline elements, we get a bunch of extra spaces! These are easy to fix once you identify the problem.

{{
  count | i18nPlural : {
    "=1": "You have 1 item.",
    other: `You have ${count} items.`,
  }
}}

To help identify these problems, I quickly wrote a simple node script using jsdom.

const jsdom = require("jsdom");
const { JSDOM } = jsdom;
const dom = new JSDOM(`<div>blah</div>`);

const ngIfElements = dom.window.document.querySelectorAll("[\\*ngIf]");
const allowedTagNames = ["DIV", "BUTTON", "MAT-SELECT", "MAT-TABLE"];
for (const element of ngIfElements) {
  // Print their type
  const tagName = element.tagName;
  if (!allowedTagNames.includes(tagName)) {
    // Print their test id
    if (element.hasAttribute("data-test-id")) {
      console.log(tagName, "-", element.getAttribute("data-test-id").trim());
    } else {
      console.log(tagName);
    }
    console.log(element.getAttribute("*ngIf").trim());
    console.log();
  }
}

Replace <div>blah</div> with the pre-migrated HTML, it prints places that may be a problem.

`*ngFor` loops without a `trackBy` function

I am so happy that track is required in the new @for loop. We have seen major performance gains from this. Without it showing an error, it is too easy to forget.

Here is how the migration script automatically adds a track.

<!-- Before -->
<ng-container *ngFor="let item of items">
  <app-item [item]="item" />
</ng-container>

<!-- After -->
@for (item of items: track item) {
  <app-item [item]="item" />
}

It works, but this is kind of the bare minimum, and you may get warnings in the browser saying it is inefficient. See the official documentation for specifics about track.
We decided to spend effort to optimize these. In most cases, we had a unique identifier we could use, like item.id:

@for (item of items: track item.id) {
  <app-item [item]="item" />
}

Sometimes we weren't sure if there was a unique identifier, but knew the list would never change. In these cases we could use $index

@for (item of listThatWillNeverChange: track $index) {
  <app-item [item]="item" />
}

And sometimes we still didn't know, so we would just use what the migration script gave us.

`ng-template` else blocks are removed

The migration script works perfectly fine here, but it is weird enough that I want to share it.

If our *ngIf statement has an else that is an <ng-template> block, the template will be removed and its contents will be put there instead.

<!-- Before -->
<ng-container *ngIf="loaded; else spinner">
  ...
</ng-container>
<ng-template #spinner>
  Loading...
</ng-template>

<!-- After -->
@if (loaded) {
  ...
} @else {
  Loading...
}

This works perfectly most of the time, but it could be problematic if we were using that template in a lot of places. In our case, it never really added a lot of code, though we did have a few components where it added 10 or more copies of that same loading block.
It's also worth noting that if you have a comment above the <ng-template> block, it won't get copied over. So watch for that.

<!-- Before -->
<ng-container *ngIf="loaded; else spinner">
  ...
</ng-container>
<!-- Else block for main container -->
<ng-template #spinner>
  Loading...
</ng-template>

<!-- After -->
@if (loaded) {
  ...
} @else {
  Loading...
}
<!-- Else block for main container -->

Random HTML in an `ngSwitch` but outside an `ngCase`

Yeah, some of our code is really bad and makes no sense. This worked before, but no longer works after the migration.

<span [ngSwitch]="count">
  Your cart is
  <ng-container *ngSwitchCase="0">
    empty.
  </ng-container>
  <ng-container *ngSwitchCase="1">
    full.
  </ng-container>
</span>

The "Your cart is" text must be outside the switch for it to work.

Your cart is
<span [ngSwitch]="count">
  <ng-container *ngSwitchCase="0">
    empty.
  </ng-container>
  <ng-container *ngSwitchCase="1">
    full.
  </ng-container>
</span>

Never formatted correctly

When you run the script, it asks if you want it to be formatted. This never worked for us, and we always had to format it ourselves after using prettier. The one problem we had to manually fix was that it would remove the imports for NgIf, NgFor, and NgSwitch, but it wouldn't remove the empty line it was on.

// Before
import { Component, inject } from "@angular/core";
import { NgIf, NgFor } from "@angular/common";
import { FormBuilder } from "@angular/forms";

// After
import { Component, inject } from "@angular/core";

import { FormBuilder } from "@angular/forms";

Kind of weird, but not that big of a deal.

The end

Those were the problems we saw and how we dealt with them. I hope this helps!

Lessons learned from Angular's control flow migration script

Jared Robertson — Fri, 06 Jun 2025 23:13:12 +0000

Do not run the script on your entire application

Avoid making non-script changes

Dangerous: Convert negated if-statements to if-else

In my opinion, the way to do an if-else statement with NgIf is difficult to read. Consequently, we would avoid using else statements, and would prefer doing something like this

<div *ngIf="loaded">
  ...
</div>
<div *ngIf="!loaded">Loading</div>

When the script runs, it will turn into this

@if (loaded) {
  <div>
    ...
  </div>
}
@if (!loaded) {
  <div>Loading</div>
}

It will be tempting to switch it to an else statement

@if (loaded) {
  <div>
    ...
  </div>
} @else {
  <div>Loading</div>
}

@if (loaded && !error) {
  <div>
    ...
  </div>
}
@if (!loaded && !error) {
  <div>Loading</div>
}

This type of change is incredibly hard for reviewers and testers to catch. Just avoid it. You can fix it later.

Dangerous: Get rid of redundant div tags

A lot of our legacy code uses <div> tags that do nothing except hold the *ngIf directive (prefer <ng-container> instead).

After the conversion, the <div> will remain, look terrible, and you may want to just remove it.

<!-- Before conversion -->
<div *ngIf="condition">
  <div class="some-container">Contents</div>
</div>

<!-- After conversion -->
@if (condition) {
  <div><!-- Possibly unnecessary div -->
    <div class="some-container">Contents</div>
  </div>
}

Not as dangerous: Replace `let i = $index` with just `$index`

Inline elements will have spacing added

This was the most common problem for us that we needed to fix. A lot of our legacy code handles plurality in a very i18n-unfriendly way:

You have {{ count }} item<span *ngIf="count !== 1">s</span>.

Output:
> You have 1 item.
> You have 3 items.

After the migration, it will change to this

You have {{ count }} item
@if (count !== 1) {
  <span>s</span>
}
.

Output:
> You have 1 item .
> You have 3 item s .

Because we are operating on inline elements, we get a bunch of extra spaces! These are easy to fix once you identify the problem.

{{
  count | i18nPlural : {
    "=1": "You have 1 item.",
    other: `You have ${count} items.`,
  }
}}

To help identify these problems, I wrote a very simple node script using jsdom.

const jsdom = require("jsdom");
const { JSDOM } = jsdom;
const dom = new JSDOM(`<div>blah</div>`);

const ngIfElements = dom.window.document.querySelectorAll("[\\*ngIf]");
const allowedTagNames = ["DIV", "BUTTON", "MAT-SELECT", "MAT-TABLE"];
for (const element of ngIfElements) {
  // Print their type
  const tagName = element.tagName;
  if (!allowedTagNames.includes(tagName)) {
    if (element.hasAttribute("data-test")) {
      console.log(tagName, "-", element.getAttribute("data-test").trim());
    } else {
      console.log(tagName);
    }
    console.log(element.getAttribute("*ngIf").trim());
    console.log();
  }
}

Replace <div>blah</div> with the pre-migrated HTML, it prints places that may be a problem.

`*ngFor` loops without a `trackBy` function

I am so happy that track is required in the new @for loop. We have seen major performance gains from this. Without it showing an error, it is too easy to forget.

Here is how the migration script automatically adds a track.

<!-- Before -->
<ng-container *ngFor="let item of items">
  <app-item [item]="item" />
</ng-container>

<!-- After -->
@for (item of items: track item) {
  <app-item [item]="item" />
}

@for (item of items: track item.id) {
  <app-item [item]="item" />
}

Sometimes we weren't sure if there was a unique identifier, but knew the list would never change. In these cases we could use $index

@for (item of listThatWillNeverChange: track $index) {
  <app-item [item]="item" />
}

And sometimes we still didn't know, so we would just use what the migration script gave us.

`ng-template` else blocks are removed

The migration script works perfectly fine here, but it is weird enough that I want to share it.

If our *ngIf statement has an else that is an <ng-template> block, the template will be removed and its contents will be put there instead.

<!-- Before -->
<ng-container *ngIf="loaded; else spinner">
  ...
</ng-container>
<ng-template #spinner>
  Loading...
</ng-template>

<!-- After -->
@if (loaded) {
  ...
} @else {
  Loading...
}

<!-- Before -->
<ng-container *ngIf="loaded; else spinner">
  ...
</ng-container>
<!-- Else block for main container -->
<ng-template #spinner>
  Loading...
</ng-template>

<!-- After -->
@if (loaded) {
  ...
} @else {
  Loading...
}
<!-- Else block for main container -->

Random HTML in an `ngSwitch` but outside an `ngCase`

Yeah, some of our code is really bad and makes no sense. This worked before, but no longer works after the migration.

<span [ngSwitch]="count">
  Your cart is
  <ng-container *ngSwitchCase="0">
    empty.
  </ng-container>
  <ng-container *ngSwitchCase="1">
    full.
  </ng-container>
</span>

The "Your cart is" text must be outside the switch for it to work.

Your cart is
<span [ngSwitch]="count">
  <ng-container *ngSwitchCase="0">
    empty.
  </ng-container>
  <ng-container *ngSwitchCase="1">
    full.
  </ng-container>
</span>

Never formatted correctly

// Before
import { Component, inject } from "@angular/core";
import { NgIf, NgFor } from "@angular/common";
import { FormBuilder } from "@angular/forms";

// After
import { Component, inject } from "@angular/core";

import { FormBuilder } from "@angular/forms";

Kind of weird, but not that big of a deal.

The end

Those were the problems we saw and how we dealt with them. I hope this helps!

TanStack Query: Angular/React differences

Jared Robertson — Wed, 09 Oct 2024 02:31:48 +0000

As I have been trying to learn Angular Query, I discovered that there is not a lot of documentation on it yet, even though it is an amazing framework. Consequently, I have been going through a lot of React Query tutorials to try to learn its best practices and bring those over to how I use Angular Query. Some of these differences, however, are not obvious, and have tripped me up. Hopefully this list will help you out until there are more tutorials and examples specific to Angular.

Differences

1. `injectQuery` in any injection context

In React, useQuery follows the Rules of hooks, namely that there are specific places where useQuery can be called, and it cannot be called anywhere else.
In Angular Query, injectQuery does not have that limitation. Under normal circumstances, we can inject it whenever we are inside an injection context. Here are some examples where it would work:

Class variables and constructors

@Component({
  standalone: true,
  templateUrl: './bulbasaur.component.html',
})
export class BulbasaurComponent {
  private readonly http = inject(HttpClient);

  // 👍
  readonly bulbasaurQuery = injectQuery(() => ({
    queryKey: ['bulbasaur'],
    queryFn: () =>
      lastValueFrom(
        this.http.get<PokeData>(
          'https://pokeapi.co/api/v2/pokemon/bulbasaur'
        ),
      ),
  }));

  constructor() {
    // 👍
    const mewQuery = injectQuery(() => ({
      queryKey: ['mew'],
      queryFn: () =>
        lastValueFrom(
          this.http.get<PokeData>(
            'https://pokeapi.co/api/v2/pokemon/mew'
          ),
        ),
      })
    );
  }
}

Anywhere the library author says

NgRx signal store features are run in an injection context. Here is how to use a query inside a signals store:

type PokeId = 'bulbasaur' | 'ivysaur' | 'venusaur';
type PokeData = {...};

interface PokemonState {
  pokeId: PokeId;
}

const initialState: PokemonState = {
  pokeId: 'bulbasaur',
};

const PokemonStore = signalStore(
  withState(initialState),
  withComputed((store) => {
    const http = inject(HttpClient);
    const { status, data } = injectQuery(() => ({
      queryKey: ['pokemon', store.pokeId()],
      queryFn: () =>
        lastValueFrom(
          http.get<PokeData>(
            `https://pokeapi.co/api/v2/pokemon/${store.pokeId()}`
          ),
        ),
    }));

    return { status, data };
  }),
  withMethods((store) => ({
    setPokeId: (pokeId: PokeId) => patchState(store, { pokeId }),
  })),
);

Anywhere else

Route guards (don't do it), resolvers, or anywhere if we include the current Injector:

@Component({
  standalone: true,
  templateUrl: './poke-prefetch.component.html',
})
export class PokemenComponent {
  private readonly http = inject(HttpClient);
  private readonly injector = inject(Injector);

  // https://bulbapedia.bulbagarden.net/wiki/Category:Male-only_Pok%C3%A9mon
  pokemen = [
    'nidoran♂',
    'nidoking',
    'hitmonlee',
    'hitmonchan',
    'tauros',
  ] as const;

  async prefetchPokemen() {
    const queryClient = injectQueryClient({ injector: this.injector });

    await Promise.all(
      this.pokemen.map((pokeman) => {
        return queryClient.prefetchQuery({
          queryKey: ['pokemon', pokeman],
          queryFn: () =>
            lastValueFrom(
              this.http.get<PokeData>(
                `https://pokeapi.co/api/v2/pokemon/${pokeman}`,
              ),
            ),
        });
      }),
    );
  }
}

2. `useQuery({...})` versus `injectQuery(() => {...})`

This is the reason for this article. I messed this up so many times when I first started. The first parameter of injectQuery is a function, not an object. But why?
It does not say anything about this in Angular Query's documentation, but it does in Solid Query:

Arguments to solid-query primitives (like createQuery, createMutation, useIsFetching) listed above are functions, so that they can be tracked in a reactive scope.

I don't know what a reactive scope is, so maybe not 😒

Just remember that injectQuery's first parameter is a function and you'll be good to go.

3. Angular gets `queryClient` for free

injectQuery's first parameter actually passes queryClient as its first parameter:

//                            👇👇
const query = injectQuery((queryClient) => ({
  queryKey, queryFn
}));

I have found this very useful with injectMutation and optimistic updates.

// No need to also add injectQueryClient()

const mutation = injectMutation((queryClient) => ({
  mutationFn: (updates) => this.service.updateThing(updates),
  onMutate: async (updates) => {
    await queryClient.cancelQueries({ queryKey });

    const snapshot = queryClient.getQueryData(queryKey);

    queryClient.setQueryData(queryKey, (prev) =>
      prev.filter((p) => p.id !== updates.id),
    );

    return snapshot;
  },
  onError: (_error, _variables, snapshot) => {
    queryClient.setQueryData(queryKey, snapshot);
  },
  onSettled: () => {
    return queryClient.invalidateQueries({ queryKey });
  },
}));

4. Superfluous differences

These may not even be worth mentioning, but here goes.

React is use* and Angular is inject*
Angular uses signals. To access data or any of the fields of the query object, add () to the end of it

// React
const MyComponent = () => {
  const { data } = useQuery({ queryKey, queryFn });

  return <p>{ data ?? '😬' }</p>;
};

// Angular
@Component({
  standalone: true, //       👇
  template: `<p>{{ query.data() ?? '😬' }}</p>`,
}) //                        👆
class MyComponent {
  query = injectQuery({ queryKey, queryFn });
}

Notes

I use injectQuery in all of the examples, but everything applies to injectMutation, too. Once injectQueries is ready, these will hopefully apply there, too.

Conclusion

That's it! Thanks for reading and I hope you learned something! Let me know if I missed anything.

Angular Query in route guards

Jared Robertson — Sun, 29 Sep 2024 03:10:30 +0000

Short version

Use queryClient.fetchQuery(...), which returns the data as a promise:

const queryClient = injectQueryClient();
const data = await queryClient.fetchQuery({
  queryKey: ['my-key'],
  queryFn: () => {},
  staleTime: 30_000, // or number greater than 0
});
return data;

Set the staleTime to a nonzero value so the route guard does not refetch every time.
Do not use injectQuery(...) or injectQueryClient().getQuery(...).

The problem

This is a real scenario I recently encountered where we were calling the same permissions endpoint multiple times on every page load.
When a user navigates to the admin dashboard, we have a route guard that fetches the admin permissions and returns true if they are an admin. Once on the page, it would fetch the admin permissions again to determine what links to show. When a user clicked on any of those links, it would fetch the admin permissions again before finally taking them to their destination.

Angular Query to the rescue

To solve this, I moved the endpoint into a queryOptions() object in the service:

// Old endpoint
getPermissions() {
  return this.http.get<Permission[]>('/api/admin-permissions');
}

// New query options
permissionOptions() {
  return queryOptions({
    queryKey: ['admin-permissions'],
    queryFn: () => {
      return lastValueFrom(
        this.http.get<Permission[]>('/api/admin-permissions'),
      );
    },
    staleTime: 30_000,
  });
}

I set a staleTime value of 30 seconds, which gives the admin plenty of time to go to the admin dashboard, find the link they want, and click it. They should be able to do all of that without having to refetch the permissions.
The component (not shown) uses injectQuery(...), which works well. There are additional complications with route guards, however.

Route guard requirements

The route guard must return an async value, since we might have the permissions cached or we might need to fetch them. Also, we cannot emit a value until the permissions have been fetched. Additionally, if we have the permissions, but the data is stale, we should refetch.
Fortunately, Angular Query has the fetchQuery function, which is designed to solve this problem. From the fetchQuery documentation:

If the query exists and the data is not invalidated or older than the given staleTime, then the data from the cache will be returned. Otherwise it will try to fetch the latest data.

Here is how the route guard looked before:

export const adminDashboardGuard: CanMatchFn = () => {
  const adminService = inject(AdminService);
  const permission: Permission = 'view:admin-dashboard';

  return adminService
    .getPermissions()
    .pipe(map((permissions) => permissions.includes(permission)));
};

And here is how it looks with fetchQuery:

export const adminDashboardGuard: CanMatchFn = async () => {
  const queryClient = injectQueryClient();
  const adminService = inject(AdminService);
  const permission: Permission = 'view:admin-dashboard';

  const permissions = await queryClient.fetchQuery(
    adminService.permissionOptions(),
  );
  return permissions.includes(permission);
};

Make the guard async, inject the query client, and call queryClient.fetchQuery() with the newly created permissionOption().
It returns a promise that we await, and then we return whether or not the admin has the view:admin-dashboard permission.
That's it!

What will not work

We cannot use injectQuery(...).data() because it returns undefined until the data has been fetched. Additionally, if the data is stale, it will emit the stale data before emitting the fetched data. injectQuery(...) works great for components, not for route guards.
We also cannot use injectQueryClient().getQueryData(...) because it is not asynchronous. If the data exists, it will return it. If the data has not been fetched, it will return undefined (or maybe null).

DEV Community: Jared Robertson

Lessons learned from Angular's control flow migration script

Do not run the script on your entire application

Avoid making non-script changes

Dangerous: Convert negated if-statements to if-else

Dangerous: Get rid of redundant div tags

Not as dangerous: Replace let i = $index with just $index

Inline elements will have spacing added

*ngFor loops without a trackBy function

ng-template else blocks are removed

Random HTML in an *ngSwitch but outside an *ngCase

Never formatted correctly

The end

Lessons learned from Angular's control flow migration script

Do not run the script on your entire application

Avoid making non-script changes

Dangerous: Convert negated if-statements to if-else

Dangerous: Get rid of redundant div tags

Not as dangerous: Replace let i = $index with just $index

Inline elements will have spacing added

*ngFor loops without a trackBy function

ng-template else blocks are removed

Random HTML in an *ngSwitch but outside an *ngCase

Never formatted correctly

The end

TanStack Query: Angular/React differences

Differences

1. injectQuery in any injection context

Class variables and constructors

Anywhere the library author says

Anywhere else

2. useQuery({...}) versus injectQuery(() => {...})

3. Angular gets queryClient for free

4. Superfluous differences

Notes

Conclusion

Angular Query in route guards

Short version

The problem

Angular Query to the rescue

Route guard requirements

What will not work

Not as dangerous: Replace `let i = $index` with just `$index`

`*ngFor` loops without a `trackBy` function

`ng-template` else blocks are removed

Random HTML in an `ngSwitch` but outside an `ngCase`

Not as dangerous: Replace `let i = $index` with just `$index`

`*ngFor` loops without a `trackBy` function

`ng-template` else blocks are removed

Random HTML in an `ngSwitch` but outside an `ngCase`

1. `injectQuery` in any injection context

2. `useQuery({...})` versus `injectQuery(() => {...})`

3. Angular gets `queryClient` for free