# raf-query

> Render-as-you-fetch data fetching for React: queries start in route loaders and React Server Components, travel to components as serializable handles, and are read with `use()` under Suspense.

Every page is also markdown: add `.md` to its URL, or request it with `Accept: text/markdown`.

## Getting started

- [Overview](https://raf-query.katt.dev/docs/overview.md): What raf-query is, the principles behind it, and how it relates to TanStack Query.
- [Installation](https://raf-query.katt.dev/docs/installation.md): Install @raf-query/react and effect with npm, pnpm, Yarn or Bun.
- [Quick start](https://raf-query.katt.dev/docs/quick-start.md): Set up a QueryClient, define a query factory, start it in a TanStack Start loader and read it with useQuery and use().
- [Coming from TanStack Query](https://raf-query.katt.dev/docs/comparison.md): How TanStack Query's APIs map onto raf-query, what stays the same, what changes about where queries start, and what we leave out on purpose.
- [Examples](https://raf-query.katt.dev/docs/examples.md): The same issue tracker built on TanStack Start, on the Next.js App Router, on React Router Framework Mode, and on TanStack Start with Effect, ready to open in CodeSandbox.

## Integrations

- [TanStack Start](https://raf-query.katt.dev/docs/tanstack-start.md): Set up raf-query with TanStack Router and Start, start queries in loaders, stream them during SSR and handle redirects.
- [React Server Components (Next.js)](https://raf-query.katt.dev/docs/react-server-components.md): Start queries in server components, send them to client components with HydrationBoundary, and refetch from the browser. For the Next.js App Router and other RSC frameworks.
- [React Router](https://raf-query.katt.dev/docs/react-router.md): Client-only apps start queries in clientLoader on the tab's client; server-rendered apps start them in loader, dehydrate the cache, and hydrate it with HydrationBoundary.
- [Using Effect](https://raf-query.katt.dev/docs/effect.md): The cache is written in Effect. Return Effects from queryFns for typed errors, services and interruption, run loaders and actions as Effects, and read the same queries from React.
- [Effect services](https://raf-query.katt.dev/docs/effect-services.md): Effect queryFns can require services. They become part of the factory's type, and QueryClient provides them from a layer.
- [Effect typed errors](https://raf-query.katt.dev/docs/effect-errors.md): An Effect queryFn's error type is the query's. useQuery returns a Result so you match failures inline; catchTag in loaders and actions; or throwOnError to an error boundary.

## Guides

- [Important defaults](https://raf-query.katt.dev/docs/important-defaults.md): When raf-query fetches, refetches, retries and garbage-collects by default, and which options change it.
- [Query keys](https://raf-query.katt.dev/docs/query-keys.md): How query keys identify cache entries, how they're hashed, and how to include a factory's input in its key.
- [Query functions](https://raf-query.katt.dev/docs/query-functions.md): What a queryFn may return, how errors are reported, and what the query function context contains.
- [Query factories](https://raf-query.katt.dev/docs/query-factories.md): Define each query once as a factory of one serializable input, shared by loaders, server components and components.
- [Starting queries](https://raf-query.katt.dev/docs/starting-queries.md): prefetch, ensure and fetch: what each returns, what it waits for, and how to choose between granular skeletons and a blocked navigation.
- [Handles](https://raf-query.katt.dev/docs/handles.md): The small, serializable object that carries a query from the loader or server to the component that reads it.
- [Reading queries](https://raf-query.katt.dev/docs/reading-queries.md): useQuery returns a stable promise and tracked controls; unwrap the promise with use() under Suspense, or pass it down to a child.
- [Caching](https://raf-query.katt.dev/docs/caching.md): The life of a cache entry, from the first request through background refetches to inactivity and garbage collection.
- [URL state and pagination](https://raf-query.katt.dev/docs/url-state-and-pagination.md): Put filters, sort and page in the URL, let the loader turn them into the query's input, and pick what shows while the new input loads.
- [Infinite queries](https://raf-query.katt.dev/docs/infinite-queries.md): Paged queries with infiniteQueryOptions, "load more" buttons, infinite scroll, bidirectional lists and maxPages.
- [Request waterfalls](https://raf-query.katt.dev/docs/request-waterfalls.md): What a request waterfall is, why it's the biggest performance problem in data fetching, and how loaders, routes and backends remove them.
- [Mutations](https://raf-query.katt.dev/docs/mutations.md): Write data with form actions and transitions, keep the UI responsive with useOptimistic, then invalidate or update the cache.
- [Query invalidation](https://raf-query.katt.dev/docs/query-invalidation.md): Mark queries stale after a write, refetch the ones on screen, and select queries with key prefixes and predicates.
- [Retries and errors](https://raf-query.katt.dev/docs/retries.md): Retry failed requests with counts, predicates or Schedules, choose delays, and show errors with error boundaries.
- [Window focus refetching](https://raf-query.katt.dev/docs/window-focus-refetching.md): Stale queries on screen refetch when the user comes back to the tab or reconnects. How to turn it off, globally or per read.
- [Polling](https://raf-query.katt.dev/docs/polling.md): Refetch a query on an interval while it's on screen with refetchInterval, and pause while the tab is hidden.
- [Background fetching indicators](https://raf-query.katt.dev/docs/background-fetching-indicators.md): Show that a query is refreshing with isFetching. Prefer the router's pending UI for navigations; useIsFetching stays for compatibility when you need a global count.
- [Query cancellation](https://raf-query.katt.dev/docs/query-cancellation.md): Pass the queryFn's AbortSignal to fetch so requests nobody needs any more are aborted, and cancel queries yourself.
- [Render optimizations](https://raf-query.katt.dev/docs/render-optimizations.md): Structural sharing, stable promises and tracked controls keep re-renders to the components whose data actually changed.
- [Query meta](https://raf-query.katt.dev/docs/query-meta.md): Attach information to queries with meta, read it in the queryFn, error handlers and devtools, and type it for the whole app.
- [Testing](https://raf-query.katt.dev/docs/testing.md): Test components and loaders that use raf-query with a fresh client per test, seeded data, a fake clock and a fake page.
- [What belongs in the cache](https://raf-query.katt.dev/docs/client-state.md): raf-query caches asynchronous data from a backend or the browser. What that leaves for URL state, local state and a client store.

## Server rendering

- [SSR and hydration](https://raf-query.katt.dev/docs/ssr-and-hydration.md): How the server's query cache streams to the browser, pending queries included, and how the browser reconciles it with its own cache.

## Reference

- [Devtools](https://raf-query.katt.dev/docs/devtools.md): Inspect the browser's query cache as it changes, refetch, invalidate, reset or remove entries, and keep the panel out of production bundles.
- [API reference](https://raf-query.katt.dev/docs/api-reference.md): Every export of @raf-query/react and @raf-query/core, QueryClient's members, query options and their defaults.

## Project

- [Credits](https://raf-query.katt.dev/docs/credits.md): raf-query builds on the design of TanStack Query, and on React, Effect and TanStack Router.

## Optional

- [Full documentation](https://raf-query.katt.dev/llms-full.txt): every page above in one file