# Add TanStack Query to an Expo App

Yes. An agent replaces hand-rolled fetch state in your Expo app with TanStack Query, persisted to MMKV, keeps the screens working, updates the tests and opens a PR.

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

## What the agent does

The agent clones the repository into its own cloud sandbox and reads how data is fetched today before it adds a provider. In an app like the `boilerplate/` of infinitered/ignite, `package.json` is on `expo` 55 with React Native 0.83, `react-native-mmkv` 3.3.3, `apisauce` for HTTP, `jest-expo` for tests and no query library at all. `app/services/api/index.ts` wraps an `apisauce` instance in an `Api` class with one method, `getEpisodes()`, that calls a podcast feed and returns either `{ kind: 'ok', episodes }` or a `GeneralApiProblem` from `apiProblem.ts`. `app/context/EpisodeContext.tsx` holds `episodes`, `favorites` and `favoritesOnly` in `useState`, exposes `fetchEpisodes`, `toggleFavorite` and `hasFavorite`, and logs an error on a failed call. `app/screens/DemoPodcastListScreen.tsx` calls `fetchEpisodes` from a `useEffect` on mount, keeps its own `isLoading` and `refreshing` state, and races the fetch against a 750 ms `delay` for the pull-to-refresh animation. `app/app.tsx` already stacks providers: `SafeAreaProvider`, `KeyboardProvider`, `ThemeProvider` and `AuthProvider`, with navigation state persisted through `app/utils/storage` on MMKV.

It adds `@tanstack/react-query`, `@tanstack/query-async-storage-persister` and `@tanstack/react-query-persist-client`, installed with `npx expo install` so versions match the SDK, and creates `app/services/query/queryClient.ts` with a `QueryClient` whose default `staleTime` and `gcTime` the agent takes from the prompt, plus a persister built on the existing MMKV storage helpers in `app/utils/storage/index.ts` rather than AsyncStorage, which the app does not have. `app/app.tsx` gets a `PersistQueryClientProvider` around the existing tree, placed outside `AuthProvider` so a logout can call `queryClient.clear()`. An `app/services/query/useEpisodes.ts` hook wraps `api.getEpisodes()` in `useQuery` with a `['episodes']` key and throws on a non-`ok` result so the query's `error` state carries the `GeneralApiProblem` kind instead of a console line.

The `EpisodeContext` keeps what is client state and loses what is server state: `favorites` and `favoritesOnly` stay, now backed by `useMMKVString` like `AuthContext` already does so they survive a restart, while `episodes` and `fetchEpisodes` go, and `episodesForList` is derived in the screen from the query data. `DemoPodcastListScreen.tsx` drops its `isLoading` and `refreshing` state for `isPending`, `isRefetching` and `refetch` from the hook, keeps the 750 ms minimum spinner with `Promise.allSettled([refetch(), delay(750)])`, and shows the existing empty state component when the query errors, with the problem kind in its message. `app/devtools/ReactotronConfig.ts` gets the query client registered so the Reactotron timeline shows cache events in development.

For tests the agent adds a `test/queryWrapper.tsx` that renders children inside a fresh `QueryClientProvider` with retries off, writes a `useEpisodes` test with `@testing-library/react-native` and `renderHook` that mocks `api.getEpisodes` for the `ok` and `server` cases, and updates any screen test that rendered the podcast list through the old context. It runs `npm run compile` (`tsc --noEmit`), `npm run lint:check` and `npm test` in the sandbox, and `npx expo export --platform web` to show the bundle still builds with the new provider in place. The two Maestro flows under `.maestro/flows/`, including `FavoritePodcast.yaml`, are left as they are because the screen's test ids do not change, and the pull request says so.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add TanStack Query to this Expo app. Read app/app.tsx, the API service under app/services/api, the context providers, the podcast list screen and the storage utilities first. Install the query packages with npx expo install, create a QueryClient with a 5 minute staleTime persisted through the app's existing MMKV storage, wrap the app in the persisted provider, and move the episodes fetch into a useQuery hook that surfaces the API problem kind as the query error. Keep favorites as client state and persist them in MMKV. Update the screen to use the hook's pending, refetching and error states while keeping the existing pull-to-refresh behaviour, register the client with Reactotron in development, add hook tests with a query wrapper, run the type check, lint, Jest and a web export, and open a pull request.",
  "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 on its own branch that changes `package.json`, `app/app.tsx`, `app/context/EpisodeContext.tsx`, `app/screens/DemoPodcastListScreen.tsx` and `app/devtools/ReactotronConfig.ts`, and adds `app/services/query/queryClient.ts`, `app/services/query/useEpisodes.ts`, `test/queryWrapper.tsx` and the hook tests. The description explains which state stayed in context and which moved to the cache, lists the query keys, and pastes the `tsc`, ESLint, Jest and `expo export` output from the sandbox.

The run's record keeps every command with its output, including the `npx expo install` resolution that picked package versions for the SDK, so a reviewer can see what was installed and that the type check passed on the new hook signatures.

Before merging, a reviewer sets the `staleTime` and persistence age for real traffic, decides whether favorites should move to the server later, and checks the screens on a device, since the sandbox proves the bundle builds and the tests pass but cannot show the pull-to-refresh animation.

## Run it on every Linear issue labelled data-fetching

In the console, an automation in the Project that has the repository, with a `linear` trigger on `linear.issue.labeled` and `labels` set to `data-fetching`, starts one run per issue with the issue as its context after the prompt; the saved prompt is the whole instruction and the trigger fills in no placeholder. The prompt asks the run to add the hook and screen change the issue describes on top of the query client the first pull request introduced, so each new endpoint arrives with its key, its hook and its test.

From your own tracker, a handler sends one `POST /o/{org}/sessions` with this body, the repository in `resources` and a `request_id` that is a UUID v5 of the issue id, so a repeated webhook returns the run already started. Set a webhook URL on the API key and Rush posts `run.completed` with `session_url` when the pull request is up.

## Why run it on Rush?

Introducing a query library is a refactor across the provider tree, a context, a screen and the tests, and the mistakes are the quiet kind: a provider placed inside the auth boundary so a logout keeps the previous user's cache, a persister that serialises a storage the app does not use, a screen that lost its refresh animation. The agent reads the real provider stack and storage helpers, keeps the screen's observable behaviour, and runs the type check, the tests and a web export in its sandbox before the pull request exists.

The sandbox is its own computer with the Node version from `engines` and the Expo tooling the repository pins, and every install and test stays in the run's record. Several apps can be migrated at once in separate sandboxes, each ending in its own pull request.

## Frequently asked questions

### Will the app still work offline after this?

Better than before. The query cache is persisted through the app's MMKV storage, so a cold start shows the last episodes list while the refetch runs, and favorites are persisted the same way. The maximum age of persisted data is a setting the pull request calls out.

### Why keep favorites in context instead of the cache?

Favorites are the user's own state with no server behind them in this app, and TanStack Query is for server state. Keeping them in `EpisodeContext`, now persisted with `useMMKVString`, keeps the two kinds of state separate and leaves a clear place to move them when a favorites endpoint exists.

### Does the existing apisauce API class go away?

No. The hook calls `api.getEpisodes()` as before and turns a non-`ok` result into a thrown error so the query carries it. The `GeneralApiProblem` kinds from `apiProblem.ts` remain the error vocabulary, and the screen shows them.

### How are the hooks tested without a network?

The tests mock `api.getEpisodes` and render the hook inside a fresh `QueryClientProvider` with retries disabled, through `renderHook` from `@testing-library/react-native`, which the repository already lists. Each test asserts the pending, success and error states in turn.

## More Expo jobs

- [Add Universal Links to an Expo App](https://getrush.ai/run/add-universal-links/expo/)
- [Migrate an Expo Project from Jest to Vitest](https://getrush.ai/run/migrate-jest-to-vitest/expo/)
- [Migrate an Expo App from React Navigation to Expo Router](https://getrush.ai/run/migrate-to-expo-router/expo/)

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

- [Cancel a Running Celery Task](https://getrush.ai/run/add-task-cancellation/celery/)
- [Add Rate Limits to Celery Tasks](https://getrush.ai/run/add-task-rate-limits/celery/)
- [Add Retries with Backoff to Celery Tasks](https://getrush.ai/run/add-task-retries/celery/)

## 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/)
