The stable package keeps the callback-based query, mutation, and signal result APIs from the experimental adapter. Most application queries therefore only need an import change. The following sections cover the breaking configuration and entrypoint changes.
Angular 20.1 or newer is required by the stable package. Upgrade Angular first if your application is on an older version. Save your work and confirm the application builds before running the migration.
Before migrating an active codebase, it is recommended that you:
Use ESLint's no-restricted-imports to restrict experimental package imports while new code adopts @tanstack/angular-query. Suppress existing imports with ESLint suppressions or a rule-specific disable comment, and remove each suppression as its import is migrated.
For a gradual import migration, a package-manager alias can let new imports use the experimental adapter before you switch packages. For example, with pnpm:
{
"dependencies": {
"@tanstack/angular-query": "npm:@tanstack/angular-query-experimental@5.90.25",
"@tanstack/angular-query-experimental": "5.90.25"
}
}Keep both names on the same resolved version and peer dependency configuration, and verify they resolve to the same adapter instance. The alias still exposes the experimental API; it does not make the stable provider signatures available. Leave devtools and inject-queries-experimental imports on their original experimental paths until the package switch so the schematic can recognize them. Replace the alias with the real stable package before running the schematic.
Install the stable package, then preview the bundled migration:
npm install @tanstack/angular-query
# With the Angular CLI
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 --skipInstallWith --skipInstall, run your package manager's install command after applying the migration to synchronize the dependencies and lockfile.
The schematic handles common migration steps like updating package and devtools imports, updating dependencies, renaming providers, and converting direct new QueryClient() provider arguments to factories. Review its warnings and the remaining sections for changes that require manual updates.
Two additional migrations are opt-in:
The schematic also discovers project.json and package.json nx configurations. It checks project-local tsconfig.spec.json and tsconfig.test.json for manually configured test runners, unless a test target supplies an explicit tsConfig. Configured includes and exclusions determine which files are migrated. Projects configured entirely through inferred plugin settings may need manual review.
npm uninstall @tanstack/angular-query-experimental
npm install @tanstack/angular-queryimport { injectQuery } from '@tanstack/angular-query'
import { injectQuery } from '@tanstack/angular-query-experimental'provideTanStackQuery no longer accepts a pre-created QueryClient. Pass a factory instead.
provideTanStackQuery(new QueryClient())
provideTanStackQuery(() => new QueryClient())provideTanStackQuery now returns one EnvironmentProviders value rather than an array. Use it in an environment injector, such as ApplicationConfig.providers, the providers passed to bootstrapApplication, route-level Route.providers, or createEnvironmentInjector. It is not supported in @Component.providers or @Directive.providers. Add the result directly; do not spread it.
providers: [...provideTanStackQuery(() => new QueryClient())]
providers: [provideTanStackQuery(() => new QueryClient())]If another provider already owns the client, resolve it inside the factory:
provideTanStackQuery(() => inject(MY_QUERY_CLIENT))Replace direct token arguments with this form.
provideAngularQuery and provideQueryClient have been removed. Use provideTanStackQuery, which handles mounting, unmounting, and default hydration. Replacing it with a bare Angular useFactory provider would omit that setup.
provideAngularQuery(new QueryClient())
provideTanStackQuery(() => new QueryClient())For provideQueryClient, rename it to provideTanStackQuery and keep the existing client factory.
injectQueryClient has been removed. Inject QueryClient directly instead:
const queryClient = injectQueryClient()
const queryClient = inject(QueryClient)Devtools no longer ship as entrypoints of the core Angular package.
npm install @tanstack/angular-query-devtoolsimport { withDevtools } from '@tanstack/angular-query-devtools'
import { withDevtools } from '@tanstack/angular-query-experimental/devtools'The production and panel entrypoints move in the same way:
import { withDevtools } from '@tanstack/angular-query-devtools/production'
import { withDevtools } from '@tanstack/angular-query-experimental/devtools/production'The devtools options callback now runs in an injection context. Remove the deps option and call inject() inside the callback instead.
const optionsFromManager = (manager: DevtoolsOptionsManager) => ({
loadDevtools: manager.loadDevtools,
})
withDevtools(optionsFromManager, { deps: [DevtoolsOptionsManager] })
withDevtools(() => optionsFromManager(inject(DevtoolsOptionsManager)))See the Devtools guide for setup, production entrypoints, and configuration options.
injectQueries is now exported from the main package. The helper must be called from an Angular injection context.
import { injectQueries } from '@tanstack/angular-query'
import {
injectQueries,
} from '@tanstack/angular-query-experimental/inject-queries-experimental'
const getQueries = () => ({ queries })
const results = injectQueries(getQueries, injector)
const results = runInInjectionContext(injector, () => injectQueries(getQueries))The queries callback is reactive, tuple inference is preserved, and combine can derive a single result:
readonly summary = injectQueries(() => ({
queries: [todosOptions(), usersOptions()],
combine: ([todos, users]) => ({
pending: todos.isPending || users.isPending,
todoCount: todos.data?.length ?? 0,
userCount: users.data?.length ?? 0,
}),
}))All stable injection helpers must run in an Angular injection context. The experimental injectQuery, injectInfiniteQuery, injectMutation, injectMutationState, injectIsFetching, and injectIsMutating accepted a second { injector } options argument. injectIsRestoring accepted that options object as its first argument. The experimental injectDevtoolsPanel also accepted a second { injector } options argument. These arguments have been removed.
injectQuery(options, { injector })
runInInjectionContext(injector, () => injectQuery(options))
injectMutation(options, { injector })
runInInjectionContext(injector, () => injectMutation(options))
injectIsFetching({ queryKey: ['todos'] }, { injector })
runInInjectionContext(injector, () =>
injectIsFetching(() => ({ queryKey: ['todos'] })),
)
injectIsRestoring({ injector })
runInInjectionContext(injector, () => injectIsRestoring())Import runInInjectionContext from @angular/core. Unlike these helpers, injectQueries previously took the injector directly, as shown above. When the old argument is undefined or an empty options object, remove it and ensure the call already runs in an injection context.
The InjectQueryOptions, InjectInfiniteQueryOptions, InjectMutationOptions, InjectMutationStateOptions, InjectIsFetchingOptions, and InjectIsMutatingOptions types have also been removed, along with the devtools InjectDevtoolsPanelOptions type. Update wrappers that use these types. The schematic reports explicit arguments, spread arguments, and imports of these removed types for manual review; it does not infer injector handling through custom wrappers.
provideTanStackQuery now dehydrates the server cache into Angular TransferState and hydrates it in the browser by default. In most SSR applications, no additional setup is necessary.
If your application already performs manual dehydration and hydration, either remove the manual implementation or disable the built-in behavior to avoid hydrating the same client twice:
provideTanStackQuery(() => new QueryClient(), withNoQueryHydration())Give each client a unique key when multiple clients use automatic hydration:
provideTanStackQuery(
() => new QueryClient(),
withHydrationKey('admin-query-cache'),
)See the SSR guide for request-scoped client setup and the interaction with Angular HttpClient transfer caching.
Observed queries, parallel queries, and mutations started through the adapter register with Angular's PendingTasks. As a result, ApplicationRef.whenStable() and fixture.whenStable() wait until that work settles.
In zone-based component tests, call fixture.autoDetectChanges() before awaiting stability. Resolve controlled operations before whenStable(); assert pending state while they remain unresolved. HTTP mutations can start asynchronously, so wait for the request itself before flushing it. isPending() does not prove that a mocked API has been called.
With fake timers, advance timers and queued microtasks before awaiting stability. Disabled queries do not fetch automatically; a manual refetch still registers pending work. See Testing for query, mutation, HTTP, and fake-timer examples.
After a query-key signal changes, data() can immediately return cached data for the new key, before another change-detection pass. Assert the state the test intends to observe rather than requiring an empty intermediate value.
Observer options no longer include throwOnError. Errors are exposed through the result's error, status, and related signals, without an automatic global report. Cached query data remains readable when a background refetch fails.
injectQuery(() => ({
queryKey: ['todos'],
queryFn: fetchTodos,
throwOnError: true,
}))
injectQuery(() => ({ queryKey: ['todos'], queryFn: fetchTodos }))Remove observer throwOnError from query, infinite-query, and mutation options, including your Angular-specific client defaults. The shared core client still accepts this option for other framework adapters, but Angular does not use it for reporting.
mutateAsync() still rejects on failure, and mutate() still returns void. Imperative options such as query.refetch({ throwOnError: true }) retain their promise-rejection behavior. To report cache failures to Angular, use the ErrorHandler guide. toResource(query).value() throws when the Resource is in its error state; guard the read with hasValue() or inspect error() first.
injectIsFetching({ queryKey: ['todos'] })
injectIsFetching(() => ({ queryKey: ['todos', userId()] }))
injectIsMutating({ mutationKey: ['save'] })
injectIsMutating(() => ({ mutationKey: ['save'] }))Calls without filters remain unchanged. Filter factories can read required inputs and signals; changing a filter updates the count without waiting for a cache event.
Methods such as refetch() and fetchNextPage() use the current options even when called immediately after changing an options signal.
Read the current injectQueries() result when calling a method after adding, removing, or reordering queries.
injectMutationState selections and injectQueries combined results are no longer deeply compared by the adapter. A newly allocated selected object or combined result can trigger consumers even when its contents match the previous value. Prefer returning existing values when possible.
Signal updates no longer enter NgZone or wait for adapter microtasks. Angular's change-detection scheduler handles rendering. Keep reading reactive values as signals; callbacks do not gain an injection context or guaranteed zone membership.
Each mutation invocation blocks stability until its promise settles, including awaited lifecycle callbacks. A later invocation completing, or calling reset(), does not release an earlier mutation's work. Destroying the owning component or injector releases its pending tasks. Queries that are paused offline continue to block stability until resumed, cancelled, or unobserved.
Pass a factory to withPersistQueryClient:
withPersistQueryClient(() => ({
persistOptions: { persister },
}))The factory runs once per injector, in an injection context, only in the browser. Create persisters that access localStorage inside this factory.
Persistence manages its restoration state automatically through withPersistQueryClient. See persistQueryClient for the options and persisters.
The stable package also includes the following compatible improvements: