# Add Offline Support to a TanStack Query React App

Yes. An agent persists your TanStack Query cache, pauses mutations while offline and resumes them on reconnect, shows an offline banner, tests it, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-offline-support/tanstack-query/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts with how the cache is built and where requests go. In a React app laid out like alan2207/bulletproof-react, `apps/react-vite/src/app/provider.tsx` creates one `QueryClient` inside `useState` with `defaultOptions` from `src/lib/react-query.ts`, which sets `refetchOnWindowFocus: false`, `retry: false` and a `staleTime` of one minute, and wraps the tree in `QueryClientProvider` with the devtools in development. `package.json` pins `@tanstack/react-query` at `^5.32.0`. Every read is a `queryOptions` object such as `getDiscussionsQueryOptions` in `src/features/discussions/api/get-discussions.ts`, every write a `useMutation` such as `useCreateDiscussion` in `create-discussion.ts`, and all of them go through the Axios instance in `src/lib/api-client.ts`, whose response interceptor turns every failure, a lost connection included, into an error notification from the zustand store in `src/components/ui/notifications`. Reload the app without a network and the loaders in `src/app/router.tsx` throw on their first `fetchQuery`.

It persists the cache first. The agent adds `@tanstack/react-query-persist-client` and `@tanstack/query-sync-storage-persister`, both published with the same version as the core package, swaps `QueryClientProvider` in `provider.tsx` for `PersistQueryClientProvider` with a `localStorage` persister, and raises `gcTime` in `queryConfig` to a day, because a query is dropped from the persisted cache after its `gcTime` and the default five minutes would leave almost nothing to restore. A `buster` string tied to the app version in `src/config/env.ts` discards a cache written by an older build, and `shouldDehydrateQuery` leaves out the `auth/me` user query that `src/lib/auth.tsx` defines through `react-query-auth`, so a signed-out user never sees a cached profile. The route loaders then find data in the restored cache through `queryClient.getQueryData` and render without a request.

Writes get the offline treatment next. `networkMode` in the mutation defaults becomes `offlineFirst`, so a `useCreateDiscussion` call made without a connection is paused rather than failed, and the agent registers `setMutationDefaults` for each mutation key with its `mutationFn`, which is what lets `PersistQueryClientProvider` resume paused mutations with `resumePausedMutations` after the cache is restored on the next load. The Axios interceptor learns to tell a network error from an HTTP error, so a paused mutation does not raise the error toast, and a small `OfflineBanner` component driven by `onlineManager.subscribe` sits in `src/components/layouts`, rendered by `ContentLayout`, saying that changes will be sent when the connection returns.

Tests use the setup the project already has: Vitest under `vite.config.ts` with `jsdom`, MSW handlers in `src/testing/mocks` and `renderApp` from `src/testing/test-utils.tsx`, which wraps the component in `AppProvider`. One test renders the discussions route, waits for the list, then calls `onlineManager.setOnline(false)`, submits the create form through the existing drawer and asserts the discussion is not in the mock database and no error toast is shown; it then calls `setOnline(true)` and asserts the row appears. A second test writes a dehydrated cache into `localStorage`, renders with the MSW server answering with a network error, and asserts the list renders from the cache. It runs `yarn test`, `yarn lint`, `yarn check-types` and `yarn build`, the steps `.github/workflows/react-vite-ci.yml` runs, and opens the pull request with the output.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add offline support to this React app using TanStack Query. Read apps/react-vite/package.json, src/app/provider.tsx, src/app/router.tsx, src/lib/react-query.ts, src/lib/api-client.ts, src/lib/auth.tsx, src/config/env.ts, src/features/discussions/api/get-discussions.ts, src/features/discussions/api/create-discussion.ts, src/components/layouts, src/components/ui/notifications/notifications-store.ts, src/testing/test-utils.tsx, src/testing/setup-tests.ts, src/testing/mocks and .github/workflows/react-vite-ci.yml first. Add @tanstack/react-query-persist-client and @tanstack/query-sync-storage-persister at the core package's version, replace QueryClientProvider with PersistQueryClientProvider and a localStorage persister, raise gcTime to a day, set a buster from the app version, and exclude the auth user query from dehydration. Set mutation networkMode to offlineFirst, register setMutationDefaults with each mutation's mutationFn so paused mutations resume after reload, and stop the Axios interceptor from raising a toast for a network error. Add an offline banner driven by onlineManager in ContentLayout. Write Vitest tests with the existing renderApp and MSW setup for a paused mutation that completes on reconnect and for a list rendered from the persisted cache without a network. Run yarn test, yarn lint, yarn check-types and yarn build, and open a pull request with the output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that changes `apps/react-vite/package.json` and the lockfile, `src/app/provider.tsx`, `src/lib/react-query.ts`, `src/lib/api-client.ts`, adds the banner under `src/components/layouts`, and adds two tests. The description shows the persister setup, which queries are kept out of the persisted cache, and the Vitest, lint, type-check and build output.

The run's record keeps the test in which a mutation made offline completes after `setOnline(true)`, and a browser session in the agent's sandbox where it loads the app, cuts the network and reloads, with the screenshot of the list rendering from cache and the banner showing, so a reviewer sees the behaviour rather than reads about it.

Before merging, a reviewer checks the list of queries excluded from persistence and adds any other that holds per-user data a shared machine should not keep, which the pull request calls out as the one judgement it could not make from the code alone.

## Run it on every Linear issue labelled agent

Offline requests arrive as product issues, one screen at a time: the list that should open on a train, the form that should not lose its text in a tunnel. With Linear connected under Settings → Connections in the console, add an automation to the Project with a `linear` trigger on `linear.issue.labeled` and the label `agent`. Its saved prompt asks for what this one asks for without naming the feature: read the query and mutation files the issue names, persist the reads, pause and resume the writes, and open a pull request with tests. The trigger adds the issue after the prompt and fills in no placeholder, so which screen comes from the issue text.

The trigger fires only when someone in your Rush org adds the label, and a change made by an app integration never fires it. A burst of labels is held to the automation's `max_runs_per_hour`. From your own server, the same run starts with this request and the issue URL in `resources`, with a `request_id` that is a UUID v5 of the issue id so a retried start returns the run already begun.

## Why run it on Rush?

Offline behaviour has to be seen to be believed, and seeing it means a browser, a network you can cut, a reload and a reconnect in sequence. The agent has all four in its sandbox: it runs the dev server, drives the browser, cuts the connection, reloads and reconnects, and the record keeps each step with its screenshot beside the Vitest run that automates the same path.

The change is a provider swap, a few defaults and a banner, which makes it easy to review and worth applying across every TanStack Query app a company runs. Each repository gets its own sandbox and its own pull request, at once, each with the same proof.

## Frequently asked questions

### Does every query end up in localStorage?

No. The persister saves what `shouldDehydrateQuery` lets through, and the agent excludes the signed-in user's profile query and anything else the pull request lists. A reviewer adds to that list for data that should not survive a sign-out on a shared machine.

### What happens to a mutation made offline if the user closes the tab?

A paused mutation is persisted with the cache, and on the next load `PersistQueryClientProvider` restores it and calls `resumePausedMutations`. That only works for mutations with a registered `mutationFn` through `setMutationDefaults`, which is why the agent registers one per mutation key.

### Why raise gcTime?

A query is removed from the cache, and so from the persisted copy, once it has been unused for `gcTime`. With the default of five minutes, a cache written when the user left would be nearly empty when they came back; a day keeps the last session's reads available for the next one.

### Will the error toast still show for a real failure?

Yes. The interceptor change tells a request that never reached the server, where Axios sets no `response`, from one the server answered with an error. The first is handled by the paused-mutation path and the banner; the second still raises the toast and the 401 redirect as before.

## More TanStack Query jobs

- [Add Optimistic Updates to a TanStack Query App](https://getrush.ai/run/add-optimistic-ui/tanstack-query/)
- [Add Query Prefetching to a TanStack Router App](https://getrush.ai/run/add-query-prefetching/tanstack-query/)
- [Add Request Cancellation to a TanStack Query App](https://getrush.ai/run/add-request-cancellation/tanstack-query/)

## The same job on other stacks

- [Add Offline Support to a React Native App](https://getrush.ai/run/add-offline-support/react-native/)

## More jobs like this: Turn a Linear label into a PR

- [Add Open Graph and Twitter Card Tags to an Eleventy Blog](https://getrush.ai/run/add-open-graph-tags/eleventy/)
- [Add Open Graph and Twitter Card Tags to a Jekyll Blog on GitHub Pages](https://getrush.ai/run/add-open-graph-tags/jekyll/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
