Preact Query

Purpose and Scope

Preact Query is the Preact-facing adapter for TanStack Query’s server-state model. In practical terms, it lets a Preact application declare asynchronous data requirements with hooks, share those results through a QueryClient, and rely on the same cache lifecycle that powers the other TanStack Query framework adapters. The project describes Query as an async state management library for fetching, caching, synchronizing, and updating server state, with protocol-agnostic fetching, background updates, pagination, infinite queries, mutations, cancellation, and Suspense support. That positioning matters for Preact users because the adapter should be understood as a UI integration layer over the common Query behavior, not as a separate data-fetching engine.

Sources: docs/config.json, docs/community-resources.md

The main reader problem for Preact users is usually orientation: which parts are Preact-specific, and which parts come from TanStack Query’s shared core concepts. Preact-specific code supplies hooks, context providers, hydration bindings, Suspense-facing APIs, and devtools integration that feel natural in a Preact component tree. The cache, query keys, mutation lifecycle, retries, stale data handling, invalidation, and background refetching concepts follow the same vocabulary used across the official documentation. The docs configuration demonstrates that TanStack Query is presented as a multi-framework documentation set rather than a single-framework library, and community resources reinforce the broader best-practice ecosystem around Query usage.

Sources: docs/config.json, docs/community-resources.md

Relevant Source Files

• docs/config.json - Defines the documentation structure and shows that TanStack Query documentation is organized by framework sections, which is the correct mental model for a Preact adapter page.
• docs/framework/angular/reference/functions/provideTanStackQuery.md - Shows the provider pattern used by a framework adapter: a QueryClient is created and supplied to the application, with optional features such as devtools layered into the setup.
• docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md - Documents the framework-agnostic promise contract for query functions and explains that TanStack Query can work with fetch, GraphQL clients, and other asynchronous data clients.
• docs/framework/angular/devtools.md - Documents devtools as an optional feature used to inspect queries and mutations, including development-mode defaults and production-loading controls in a framework adapter.
• docs/framework/angular/guides/background-fetching-indicators.md - Shows how adapter APIs expose per-query fetching state and global fetching indicators for background refetch UX.
• docs/community-resources.md - Lists community learning material and utilities such as GraphQL code generation, query key helpers, and OpenAPI client generation that also apply to Preact applications using TanStack Query.

Core Primitives

A Preact Query application starts with a QueryClient. The QueryClient is the object that owns query and mutation caches, default options, invalidation APIs, prefetching APIs, and cache inspection methods. Framework adapters then provide that client to the component tree so hooks can subscribe to cache state. The Angular provider reference is not Preact code, but it captures the shared adapter contract clearly: create a QueryClient, install it at the application boundary, and optionally attach features such as developer tools. In Preact, the equivalent architectural concern is the same: construct one client for the relevant app scope and make it available before components call query or mutation hooks.

Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md

Queries are the read side of the model. A query is identified by a query key and executed by a query function that returns a promise. The supplied data-client guide states that TanStack Query’s fetching mechanisms are built agnostically on promises, so the adapter does not require a special transport. In a Preact component, the query function can use browser fetch, a generated OpenAPI client, a GraphQL client, or another promise-returning abstraction. The key design constraint is that the query key must represent the resource and inputs well enough for cache sharing, invalidation, prefetching, and devtools inspection to all refer to the same cached entity.

Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md, docs/community-resources.md

Mutations are the write side of the model. While the targeted sources focus more on providers, devtools, and fetching indicators, the product documentation frames mutations as a first-class lifecycle for pending UI, optimistic writes, rollback, invalidation, and follow-up refetches. For Preact users, that means mutation hooks should be treated as coordinated server-state workflows rather than isolated event handlers. A mutation can update remote state, expose pending and error states to the UI, and then invalidate related query keys so the shared cache converges with the server.

Sources: docs/config.json, docs/community-resources.md

Setup Pattern

The Preact setup flow mirrors the common adapter shape used throughout the repository documentation. Install the Preact adapter package, create a QueryClient, wrap the application with the adapter’s provider, and then call query hooks from child components. Keep the client stable rather than recreating it on every render, because the client owns the cache and observer graph. The provider reference for Angular names this responsibility directly: it sets up the providers necessary to enable TanStack Query functionality for an application and accepts a QueryClient plus optional feature configuration.

Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md

import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/preact-query'
 
const queryClient = new QueryClient()
 
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Repo />
    </QueryClientProvider>
  )
}
 
function Repo() {
  const query = useQuery({
    queryKey: ['repoData'],
    queryFn: () =>
      fetch('https://api.github.com/repos/tanstack/query').then((res) =>
        res.json(),
      ),
  })
 
  if (query.isPending) return <span>Loading...</span>
  if (query.isError) return <span>Error: {query.error.message}</span>
 
  return <pre>{JSON.stringify(query.data, null, 2)}</pre>
}

This example uses the public Preact package name and the same first concepts a React Query user would recognize: QueryClient, QueryClientProvider, and useQuery. The fetching guide’s promise-based rule is the important portability point. Because query functions are promise-based, the UI framework does not dictate the network stack. A Preact application can begin with fetch, later replace the body of the queryFn with a generated client, and still keep the same query key, cache identity, background refetch behavior, and invalidation strategy.

Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

Hooks, Hydration, and Suspense

Preact Query hooks are the component-facing subscription layer. A hook reads options, registers interest in a cache entry, and returns a result object that the component can render. The background-fetching guide demonstrates the adapter pattern for exposing both primary lifecycle state and background refetch state: a component can show an initial loading state, an error state, a success state, and a separate refreshing indicator while cached data remains visible. In Preact, this separation is central to good UX because server data can be stale, refetching, and still useful at the same time.

Sources: docs/framework/angular/guides/background-fetching-indicators.md

Hydration is the handoff between a cache prepared outside the current client render and the live client used by the browser. In TanStack Query terms, server rendering and prefetching can populate a dehydrated cache snapshot, then the framework adapter reattaches that data so hooks begin with useful cached results instead of duplicating work. Preact users should treat hydration as part of the provider boundary: create or receive the QueryClient, restore the dehydrated state at the correct point in the tree, and then let normal hooks observe the hydrated cache.

Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md, docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

Suspense support follows the same division of responsibilities. The cache and observer model know whether data is pending, successful, errored, or refetching; the Preact adapter exposes APIs that can integrate those states with Preact’s rendering semantics. Use Suspense-oriented APIs when you want pending reads to be handled by a boundary rather than by explicit isPending branches in every component. Use the ordinary hook result shape when local loading, refreshing, retry, and partial UI states need to remain visible in the component itself.

Sources: docs/framework/angular/guides/background-fetching-indicators.md

Devtools and Debugging

Devtools make the server-state cache visible. The supplied devtools documentation explains that framework-specific devtools help inspect queries and mutations, and it also points to browser extensions for Chrome, Firefox, and Edge that provide TanStack Query debugging directly in browser DevTools. For Preact applications, the practical recommendation is to add the Preact devtools package or use the browser extension early in development. Query keys, observer counts, freshness, errors, retries, and mutation state are much easier to reason about when they are visible instead of inferred from component logs.

Sources: docs/framework/angular/devtools.md

import { QueryClient, QueryClientProvider } from '@tanstack/preact-query'
import { ReactQueryDevtools } from '@tanstack/preact-query-devtools'
 
const queryClient = new QueryClient()
 
export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Routes />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

The Angular devtools page also documents an important operational principle: devtools are treated as an optional feature and production inclusion should be deliberate. Even though the exact import path differs by framework package, the same discipline applies to Preact projects. Keep devtools available during local development, understand whether your bundler includes them in production builds, and prefer lazy or environment-gated loading if a deployed debugging surface is needed for staging or support workflows.

Sources: docs/framework/angular/devtools.md, docs/framework/angular/reference/functions/provideTanStackQuery.md

System-to-Code Mapping

Next Steps

Start with the smallest working Preact setup: one stable QueryClient, one provider near the root, and one useQuery call with a meaningful query key. After that, add devtools and watch the cache while navigating, refetching, and mutating data. Once the cache model is clear, move repeated options into shared helpers, design query keys intentionally, and adopt prefetching, hydration, Suspense, or persistence only where the application flow needs them. The related pages to read next are the core query concepts, query keys, mutations, devtools, and SSR/hydration pages.