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).
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
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
The 5 rules (non-negotiable)
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).
One QueryClient per app, mounted at the root layout. Never instantiate per-screen.
Query keys are arrays, hierarchical, with the most specific filter last: ["posts", "list", { filter }]. NEVER stringly-typed keys.
Every mutation invalidates the queries it affects. Use queryClient.invalidateQueries({ queryKey: [...] }) in onSuccess. Optimistic updates use onMutate + onError rollback.
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-setup.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).
