Rn Data Fetching

---
name: rn-data-fetching
description: 'Use when fetching data from APIs in React Native: choosing between fetch+useEffect (didactic only) and TanStack Query (production default), wiring the QueryClient provider, building queries / mutations / optimistic updates / paginated and infinite lists / cache invalidation / refetch on focus, handling loading and error states, AsyncStorage persistence, offline-first behavior. Triggers on: "fetch posts from API", "infinite scroll", "optimistic mutation", "cache invalidation", "loading state". Not for: styling lists (rn-styling), backend setup (rn-backend, Wave 3 — provider-agnostic), GraphQL clients (out of scope).'
---

# rn-data-fetching — guardrail for data fetching in React Native + Expo

> For the current Expo API and per-version details, verify against the Expo docs / MCP `mcp.expo.dev` / `expo/skills` (see rn-fundamentals → Source of truth).

## The 5 rules (non-negotiable)

1. **TanStack Query is the default** for any data that comes from the network. `fetch + useEffect` is acceptable ONLY in didactic examples or for one-off bootstrap calls (e.g. reading a config at app start).
2. **One `QueryClient` per app, mounted at the root layout.** Never instantiate per-screen.
3. **Query keys are arrays**, hierarchical, with the most specific filter last: `["posts", "list", { filter }]`. NEVER stringly-typed keys.
4. **Every mutation invalidates the queries it affects**. Use `queryClient.invalidateQueries({ queryKey: [...] })` in `onSuccess`. Optimistic updates use `onMutate` + `onError` rollback.
5. **`staleTime` ≥ 60_000 ms is the default** to avoid refetch-on-focus storms. Tune per query based on freshness need.

## Quick decision tree

- "Should I use fetch or TanStack Query?" → `references/decision-tree.md`
- "How do I set up TanStack Query in a fresh Expo app?" → `references/tanstack-query-rn.md`
- "What's the right query key shape, the right cancel pattern, the right loading state?" → `references/patterns.md`
- "Show me a working query / mutation / infinite scroll example" → `references/examples/`
- "Why does my fetch race on unmount?" → `references/concepts.md`

## Common anti-patterns (NEVER do)

- ❌ `useEffect(() => { fetch(...).then(setData) }, [])` for production data — no retry, no dedup, no cancel.
- ❌ `useState<Data | null>(null)` + `useState<boolean>(false)` for loading — let TanStack Query own server state.
- ❌ `queryKey: "posts"` as a string — must be an array.
- ❌ Calling `setData` after the component unmounts — TanStack Query handles cancel automatically.
- ❌ Mutation that updates the server but does NOT `invalidateQueries` — UI shows stale data.
- ❌ Refetching on every navigation — set `staleTime` per query.

## Sources

- Course: codewithbeto.dev/rnCourse — lesson 7 "Fetching Data from an API" + lesson 8 "Rendering Lists and TypeScript" (free).
- Official: https://tanstack.com/query/v5/docs/framework/react/overview
- Official: https://tanstack.com/query/v5/docs/framework/react/guides/mutations
- Official: https://docs.expo.dev/develop/development-builds/use-development-builds/