TanStack
Guides & Concepts

Migrating from ngneat/query

Angular Query requires Angular 20.1 or newer.

This guide uses @ngneat/query in its examples.

Active codebase recommendations

For a gradual migration:

  • Install @tanstack/angular-query alongside the legacy package and share one QueryClient, so migrated and existing code use the same cache, defaults, and invalidations.
  • Block @ngneat/query imports and its subpaths with ESLint's no-restricted-imports or a similar rule, so new code uses @tanstack/angular-query.
  • Share a test-provider helper or client factory so migrated tests keep the same client defaults.

Suppress existing imports and the temporary provider bridge with ESLint suppressions or a rule-specific disable comment, and remove each suppression as its import is migrated.

Keep the existing ngneat client configuration and let the stable adapter resolve that client:

ts
import { ApplicationConfig } from '@angular/core'
import {
  injectQueryClient as injectLegacyQueryClient,
  provideQueryClientOptions,
} from '@ngneat/query'
import { provideTanStackQuery } from '@tanstack/angular-query'

export const appConfig: ApplicationConfig = {
  providers: [
    provideQueryClientOptions({
      // Keep your existing client options here.
    }),
    provideTanStackQuery(() => injectLegacyQueryClient()),
  ],
}

This preserves the legacy client's Observable-aware methods while both adapters use the same instance. Keep query keys consistent between migrated and legacy code.

Use package versions that support the same Angular and @tanstack/query-core versions. If the lockfile selects different core versions, align the direct core dependency required by ngneat with the stable adapter's dependency. You may need root-level npm overrides or pnpm overrides to select one version within both supported ranges.

After migrating the remaining legacy code, replace the bridge with a QueryClient factory from @tanstack/angular-query, move the client options into that factory, and remove the legacy packages.

Replace the packages

Remove whichever legacy package name your application uses, along with its devtools package. The stable adapter includes @tanstack/query-core as a dependency, so remove a direct installation unless your application imports it independently.

shell
npm uninstall @ngneat/query @ngneat/query-devtools @tanstack/query-core
npm install @tanstack/angular-query @tanstack/angular-query-devtools

Configure the QueryClient

Replace provideQueryClientOptions with a QueryClient factory passed to provideTanStackQuery. The factory runs in an Angular injection context, so it can call inject() when building caches or default options.

ts
import { QueryCache } from '@ngneat/query'
import { provideQueryClientOptions } from '@ngneat/query'
import { QueryCache, QueryClient } from '@tanstack/angular-query'
import { provideTanStackQuery } from '@tanstack/angular-query'

const queryClientConfig = {
  queryCache: new QueryCache({ onError: handleError }),
}

providers: [
  provideQueryClientOptions(queryClientConfig),
  provideTanStackQuery(() => new QueryClient(queryClientConfig)),
]

Migrate queries

The legacy injectQuery() call returned a function that accepted query options. The stable API accepts a reactive options callback and returns the query result directly.

ts
private readonly useQuery = injectQuery()

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

Read signals inside the callback to update options reactively. This replaces calling updateOptions yourself.

ts
readonly filter = signal('')
private readonly useQuery = injectQuery()
readonly todos = this.useQuery({
  queryKey: ['todos', this.filter()],
  queryFn: () => fetchTodos(this.filter()),
})
readonly todos = injectQuery(() => ({
  queryKey: ['todos', this.filter()],
  queryFn: () => fetchTodos(this.filter()),
}))

When a helper must be called from a callback that is not already in an injection context, use Angular's runInInjectionContext at the call site:

ts
runInInjectionContext(injector, () => injectQuery(() => queryOptions))

Migrate infinite queries and mutations

injectInfiniteQuery and injectMutation use the same callback pattern:

ts
private readonly useInfiniteQuery = injectInfiniteQuery()
readonly posts = this.useInfiniteQuery({
  queryKey: ['posts'],
  queryFn: ({ pageParam }) => fetchPosts(pageParam),
  initialPageParam: 0,
  getNextPageParam: (lastPage) => lastPage.nextId,
})
readonly posts = injectInfiniteQuery(() => ({
  queryKey: ['posts'],
  queryFn: ({ pageParam }) => fetchPosts(pageParam),
  initialPageParam: 0,
  getNextPageParam: (lastPage) => lastPage.nextId,
}))
ts
private readonly useMutation = injectMutation()
readonly addTodo = this.useMutation({
  mutationFn: addTodo,
})
readonly addTodo = injectMutation(() => ({
  mutationFn: addTodo,
}))

Imperative methods remain direct methods, for example addTodo.mutate(value), addTodo.reset(), posts.fetchNextPage(), and todos.refetch().

Migrate query and mutation results

The legacy adapter exposed one signal and one Observable containing the entire observer result. The stable adapter exposes each result field as a signal and keeps imperative methods as functions.

ts
todos.result().isPending
todos.result().data
todos.result().error
todos.isPending()
todos.data()
todos.error()

Templates use the field signals in the same way:

html
@if (todos.result().isPending) {
@if (todos.isPending()) {
  <span>Loading...</span>
} @else if (todos.isError()) {
  <span>{{ todos.error()?.message }}</span>
} @else {
  @for (todo of todos.data(); track todo.id) {
    <span>{{ todo.title }}</span>
  }
}

There is no direct replacement for result$. Convert the field signal you need with Angular's toObservable, or compose several fields with computed first.

ts
readonly todosResult$ = this.todos.result$
readonly todosState = computed(() => ({
  data: this.todos.data(),
  error: this.todos.error(),
  status: this.todos.status(),
}))
readonly todosResult$ = toObservable(this.todosState)

Mutation state follows the same rule:

ts
addTodo.result().isPending
addTodo.result().data
addTodo.isPending()
addTodo.data()

Convert Observable query functions

The legacy adapter accepted an RxJS Observable from queryFn and mutationFn. The stable adapter follows TanStack Query's Promise-based contract, so convert an Observable with firstValueFrom or lastValueFrom.

ts
queryFn: () => this.http.get<Todo[]>('/api/todos')
queryFn: () => lastValueFrom(this.http.get<Todo[]>('/api/todos'))
ts
const createTodo = (todo: Todo) => this.http.post<Todo>('/api/todos', todo)

mutationFn: createTodo
mutationFn: (todo) => lastValueFrom(createTodo(todo))

See Angular HttpClient for a complete example. If an Observable does not complete, prefer firstValueFrom or make it complete before converting it.

Migrate background indicators

injectIsFetching and injectIsMutating now accept a reactive filters callback and return a Signal<number>.

ts
private readonly useIsFetching = injectIsFetching()
readonly fetchingTodos =
  this.useIsFetching({ queryKey: ['todos'] }).toSignal()
readonly fetchingTodos = injectIsFetching(() => ({ queryKey: ['todos'] }))
ts
private readonly useIsMutating = injectIsMutating()
readonly mutatingTodos =
  this.useIsMutating({ mutationKey: ['todos'] }).toSignal()
readonly mutatingTodos = injectIsMutating(() => ({ mutationKey: ['todos'] }))

Use toObservable(this.fetchingTodos) if a consumer still needs an Observable.

Inject the QueryClient

Use Angular dependency injection directly instead of injectQueryClient:

ts
import { injectQueryClient } from '@ngneat/query'
import { inject } from '@angular/core'
import { QueryClient } from '@tanstack/angular-query'

private readonly queryClient = injectQueryClient()
private readonly queryClient = inject(QueryClient)

Migrate devtools

Replace the legacy devtools provider with the withDevtools feature from the standalone Angular Query devtools package.

ts
import { provideQueryClientOptions } from '@ngneat/query'
import { provideQueryDevTools } from '@ngneat/query-devtools'
import { QueryClient, provideTanStackQuery } from '@tanstack/angular-query'
import { withDevtools } from '@tanstack/angular-query-devtools'

const devtools = withDevtools(() => ({ initialIsOpen: true }))

providers: [
  provideQueryClientOptions({}),
  provideQueryDevTools({ initialIsOpen: true }),
  provideTanStackQuery(() => new QueryClient(), devtools),
]

See the Devtools guide for production entrypoints and reactive options.

See Error handling for optional Angular ErrorHandler integration.