# 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 with npm, pnpm, Yarn or Bun.
- [Quick start](https://raf-query.katt.dev/docs/quick-start.md): Create a query client, define a post and its paged comments, start them in a TanStack Start loader, read them with useQuery, useInfiniteQuery and use(), and add a comment.
- [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 and on React Router Framework Mode, 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.

## Guides

- [Important defaults](https://raf-query.katt.dev/docs/important-defaults.md): When raf-query fetches, refetches, retries and garbage-collects, which behaviors are on 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 groups name sets of queries, 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): load with prefetch, swr and revalidate: what each waits for, what it returns, 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 thenable and the query's state; read it with use() under Suspense, switch on its status, 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 with whilePending.
- [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 in React actions inside forms 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 by factory, group or predicate, such as tags.
- [Retries and errors](https://raf-query.katt.dev/docs/retries.md): Retry failed requests with the retry() link, set attempts per query in meta, choose delays and which errors to retry, time requests out, and show errors.
- [Window focus refetching](https://raf-query.katt.dev/docs/window-focus-refetching.md): Refetch stale queries on screen when the user comes back to the tab or reconnects, with the focusRefetch() and reconnectRefetch() features, and opt queries out in meta.
- [Polling](https://raf-query.katt.dev/docs/polling.md): Refetch a query on an interval while it's on screen with meta.refetchInterval and the polling() feature.
- [Background fetching indicators](https://raf-query.katt.dev/docs/background-fetching-indicators.md): Show that a query is refreshing with its state's isFetching, count requests in flight with useIsFetching, and leave navigations to the router's pending UI.
- [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 know when raf-query aborts them.
- [Render optimizations](https://raf-query.katt.dev/docs/render-optimizations.md): Tracked state, structural sharing, stable thenables and select keep readers from re-rendering, and the data's identity stable, when nothing they use changed.
- [Query meta](https://raf-query.katt.dev/docs/query-meta.md): Set per-query options for the client's links and features with meta, declare your own fields, and type meta by the client it belongs to.
- [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, an injectable clock and real browser events.
- [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 and recent loads as they change, refetch, 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, its TanStack Router subpath and @raf-query/core, with 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 and TanStack Router.

## Optional

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