All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

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

Keep reading