- Important Defaults
- Queries
- Query Keys
- Query Functions
- Query Options
- Network Mode
- Parallel Queries
- Dependent Queries
- Background Fetching Indicators
- Window Focus Refetching
- Disabling/Pausing Queries
- Query Retries
- Paginated Queries
- Infinite Queries
- Initial Query Data
- Placeholder Query Data
- Mutations
- Mutation Options
- Query Invalidation
- Invalidation from Mutations
- Optimistic Updates
- Query Cancellation
- Scroll Restoration
- Filters
- Caching
- Default Query Fn
- SSR
- Testing
- Does this replace state managers?
- Migrating from Experimental
- Migrating from ngneat/query
- Error Handling
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:
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.
npm uninstall @ngneat/query @ngneat/query-devtools @tanstack/query-core
npm install @tanstack/angular-query @tanstack/angular-query-devtoolsConfigure 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.
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.
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.
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:
runInInjectionContext(injector, () => injectQuery(() => queryOptions))Migrate infinite queries and mutations#
injectInfiniteQuery and injectMutation use the same callback pattern:
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,
}))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.
todos.result().isPending
todos.result().data
todos.result().error
todos.isPending()
todos.data()
todos.error()Templates use the field signals in the same way:
@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.
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:
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.
queryFn: () => this.http.get<Todo[]>('/api/todos')
queryFn: () => lastValueFrom(this.http.get<Todo[]>('/api/todos'))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>.
private readonly useIsFetching = injectIsFetching()
readonly fetchingTodos =
this.useIsFetching({ queryKey: ['todos'] }).toSignal()
readonly fetchingTodos = injectIsFetching(() => ({ queryKey: ['todos'] }))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:
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.
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.