Angular developers have used TanStack Query through the @tanstack/angular-query-experimental package for a long time. On 17 November 2026, the stable package @tanstack/angular-query was published: 5.0.0 first, then 5.108.0 the same day, when the Angular packages joined the same release group as @tanstack/query-core. The query and mutation APIs you know mostly stay the same, but setup, injectors, devtools, SSR hydration and error handling have changed. This tutorial shows how to start fresh and how to migrate an existing app safely.

Sources: the official Angular Query docs, the migration guide and the TanStack Query releases.

Requirements

  • Angular 20.1 or newer. Upgrade Angular first if you’re on an older version.
  • Commit your work and confirm the app builds before you migrate.

Option A: Start a new project

The Angular CLI schematic installs the package and devtools, then configures an SSR-safe QueryClient factory with withDevtools():

ng add @tanstack/angular-query

Or install it manually:

npm i @tanstack/angular-query
npm i @tanstack/angular-query-devtools   # optional

Register the client with a factory:

// main.ts
import { provideHttpClient } from '@angular/common/http'
import { bootstrapApplication } from '@angular/platform-browser'
import { provideTanStackQuery, QueryClient } from '@tanstack/angular-query'
import { AppComponent } from './app/app.component'

bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(),
    provideTanStackQuery(() => new QueryClient()),
  ],
})

Then use signals-based queries and mutations in a component:

import { HttpClient } from '@angular/common/http'
import { Component, Injectable, inject } from '@angular/core'
import { injectMutation, injectQuery, QueryClient } from '@tanstack/angular-query'
import { lastValueFrom } from 'rxjs'

interface Todo { id: string; title: string }

@Injectable({ providedIn: 'root' })
export class TodoService {
  private readonly http = inject(HttpClient)

  getTodos(): Promise<Todo[]> {
    return lastValueFrom(this.http.get<Todo[]>('/api/todos'))
  }

  addTodo(todo: Todo): Promise<Todo> {
    return lastValueFrom(this.http.post<Todo>('/api/todos', todo))
  }
}

@Component({
  selector: 'app-todos',
  template: `
    <button (click)="add()" [disabled]="addTodo.isPending()">Add todo</button>

    @if (todos.isPending()) {
      <p>Loading…</p>
    } @else if (todos.isError()) {
      <p>Could not load todos.</p>
    } @else {
      <ul>
        @for (todo of todos.data(); track todo.id) {
          <li>{{ todo.title }}</li>
        }
      </ul>
    }
  `,
})
export class TodosComponent {
  private readonly api = inject(TodoService)
  private readonly queryClient = inject(QueryClient)

  readonly todos = injectQuery(() => ({
    queryKey: ['todos'],
    queryFn: () => this.api.getTodos(),
  }))

  readonly addTodo = injectMutation(() => ({
    mutationFn: (todo: Todo) => this.api.addTodo(todo),
    onSuccess: () => this.queryClient.invalidateQueries({ queryKey: ['todos'] }),
  }))

  add() {
    this.addTodo.mutate({ id: Date.now().toString(), title: 'Write blog post' })
  }
}

Every result field, such as data(), isPending() and isError(), is an Angular signal, so it works naturally with zoneless change detection and @if/@for.

Option B: Migrate from the experimental package

Step 1: Run the migration schematic

Install the stable package, preview the changes, then apply them:

npm install @tanstack/angular-query

ng generate @tanstack/angular-query:migrate-from-experimental --dry-run
ng generate @tanstack/angular-query:migrate-from-experimental

With Nx:

nx g @tanstack/angular-query:migrate-from-experimental --skipInstall

The schematic updates package and devtools imports, updates dependencies, renames providers, and converts direct new QueryClient() provider arguments into factories. Two migrations are opt-in: --unsafe-wrap-client-references (for things like provideTanStackQuery(client)) and --migrate-query-core-imports (moves @tanstack/query-core imports to the Angular package). Read every warning it prints. The sections below cover what still needs a human.

Step 2: Provider changes

provideTanStackQuery no longer accepts a ready-made client, and it returns a single EnvironmentProviders value rather than an array, so don’t spread it:

// Before
providers: [...provideTanStackQuery(new QueryClient())]

// After
providers: [provideTanStackQuery(() => new QueryClient())]

It belongs in an environment injector: ApplicationConfig.providers, bootstrapApplication, a route’s providers, or createEnvironmentInjector. It is not supported in @Component.providers. If another provider already owns the client, resolve it inside the factory: provideTanStackQuery(() => inject(MY_QUERY_CLIENT)).

provideAngularQuery and provideQueryClient are removed, and so is injectQueryClient(). Inject the class directly:

const queryClient = inject(QueryClient)

Step 3: No more { injector } arguments

The experimental injectQuery, injectMutation, injectInfiniteQuery, injectIsFetching and related helpers accepted a second { injector } argument. That argument is gone, so call them inside an injection context instead:

import { runInInjectionContext } from '@angular/core'

// Before
injectQuery(options, { injector })

// After
runInInjectionContext(injector, () => injectQuery(options))

injectQueries is now exported from the main package and supports combine:

import { injectQueries } from '@tanstack/angular-query'

readonly summary = injectQueries(() => ({
  queries: [todosOptions(), usersOptions()],
  combine: ([todos, users]) => ({
    pending: todos.isPending || users.isPending,
    todoCount: todos.data?.length ?? 0,
    userCount: users.data?.length ?? 0,
  }),
}))

Activity filters must now be reactive functions:

injectIsFetching(() => ({ queryKey: ['todos', this.userId()] }))
injectIsMutating(() => ({ mutationKey: ['save'] }))

Step 4: Devtools moved to their own package

npm install @tanstack/angular-query-devtools
// Before
import { withDevtools } from '@tanstack/angular-query-experimental/devtools'
// After
import { withDevtools } from '@tanstack/angular-query-devtools'

The devtools options callback now runs in an injection context, so drop the deps option and call inject() inside it.

Step 5: Error handling changes

Observer options no longer support throwOnError. Errors are exposed through error(), status() and related signals, and cached data stays readable if a background refetch fails. Remove throwOnError from query, infinite-query and mutation options, including your Angular client defaults:

// Before
injectQuery(() => ({ queryKey: ['todos'], queryFn: fetchTodos, throwOnError: true }))

// After
injectQuery(() => ({ queryKey: ['todos'], queryFn: fetchTodos }))

mutateAsync() still rejects on failure, and query.refetch({ throwOnError: true }) still rejects as before. To report failures globally, use Angular’s ErrorHandler, as described in the docs.

Step 6: SSR hydration is automatic

provideTanStackQuery now dehydrates the server cache into Angular TransferState and hydrates it in the browser by default. If you wrote your own dehydrate/hydrate code, delete it or turn off the built-in behaviour so the client isn’t hydrated twice:

import { provideTanStackQuery, QueryClient, withNoQueryHydration } from '@tanstack/angular-query'

provideTanStackQuery(() => new QueryClient(), withNoQueryHydration())

Using several clients? Give each a unique key with withHydrationKey('admin-query-cache').

Step 7: Fix tests that wait for stability

Queries and mutations now register with Angular’s PendingTasks, so fixture.whenStable() and ApplicationRef.whenStable() wait for them to settle. In zone-based component tests, call fixture.autoDetectChanges() before awaiting stability, and resolve mocked requests before whenStable(), or the test will wait for ever.

Bonus: Angular Resources

If an Angular API expects a Resource, convert a query with toResource(). It is marked experimental, so pin an exact version if you use it:

import { injectQuery, toResource } from '@tanstack/angular-query'

readonly todoQuery = injectQuery(() => ({
  queryKey: ['todo', this.id()],
  queryFn: () => fetchTodo(this.id()),
}))
readonly todo = toResource(this.todoQuery)   // todo.hasValue(), todo.value()

Takeaway

TanStack Query for Angular is officially stable. For most apps, migrating means running one schematic and then fixing four things by hand: client factories, injection contexts instead of { injector }, the separate devtools package, and the removal of throwOnError. Do it on a branch, read the schematic warnings, and run your tests, because the new PendingTasks integration can change how they settle.