1---
2name: native-data-fetching
3description: Use when implementing or debugging ANY network request, API call, or data fetching. Covers fetch API, React Query, SWR, error handling, caching, offline support, and Expo Router data loaders (`useLoaderData`).
4version: 1.0.0
5license: MIT
6---
7 
8# Expo Networking
9 
10**You MUST use this skill for ANY networking work including API requests, data fetching, caching, or network debugging.**
11 
12## References
13 
14Consult these resources as needed:
15 
16```
17references/
18  expo-router-loaders.md   Route-level data loading with Expo Router loaders (web, SDK 55+)
19```
20 
21## When to Use
22 
23Use this skill when:
24 
25- Implementing API requests
26- Setting up data fetching (React Query, SWR)
27- Using Expo Router data loaders (`useLoaderData`, web SDK 55+)
28- Debugging network failures
29- Implementing caching strategies
30- Handling offline scenarios
31- Authentication/token management
32- Configuring API URLs and environment variables
33 
34## Preferences
35 
36- Avoid axios, prefer expo/fetch
37 
38## Common Issues & Solutions
39 
40### 1. Basic Fetch Usage
41 
42**Simple GET request**:
43 
44```tsx
45const fetchUser = async (userId: string) => {
46  const response = await fetch(`https://api.example.com/users/${userId}`);
47 
48  if (!response.ok) {
49    throw new Error(`HTTP error! status: ${response.status}`);
50  }
51 
52  return response.json();
53};
54```
55 
56**POST request with body**:
57 
58```tsx
59const createUser = async (userData: UserData) => {
60  const response = await fetch("https://api.example.com/users", {
61    method: "POST",
62    headers: {
63      "Content-Type": "application/json",
64      Authorization: `Bearer ${token}`,
65    },
66    body: JSON.stringify(userData),
67  });
68 
69  if (!response.ok) {
70    const error = await response.json();
71    throw new Error(error.message);
72  }
73 
74  return response.json();
75};
76```
77 
78---
79 
80### 2. React Query (TanStack Query)
81 
82**Setup**:
83 
84```tsx
85// app/_layout.tsx
86import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
87 
88const queryClient = new QueryClient({
89  defaultOptions: {
90    queries: {
91      staleTime: 1000 * 60 * 5, // 5 minutes
92      retry: 2,
93    },
94  },
95});
96 
97export default function RootLayout() {
98  return (
99    <QueryClientProvider client={queryClient}>
100      <Stack />
101    </QueryClientProvider>
102  );
103}
104```
105 
106**Fetching data**:
107 
108```tsx
109import { useQuery } from "@tanstack/react-query";
110 
111function UserProfile({ userId }: { userId: string }) {
112  const { data, isLoading, error, refetch } = useQuery({
113    queryKey: ["user", userId],
114    queryFn: () => fetchUser(userId),
115  });
116 
117  if (isLoading) return <Loading />;
118  if (error) return <Error message={error.message} />;
119 
120  return <Profile user={data} />;
121}
122```
123 
124**Mutations**:
125 
126```tsx
127import { useMutation, useQueryClient } from "@tanstack/react-query";
128 
129function CreateUserForm() {
130  const queryClient = useQueryClient();
131 
132  const mutation = useMutation({
133    mutationFn: createUser,
134    onSuccess: () => {
135      // Invalidate and refetch
136      queryClient.invalidateQueries({ queryKey: ["users"] });
137    },
138  });
139 
140  const handleSubmit = (data: UserData) => {
141    mutation.mutate(data);
142  };
143 
144  return <Form onSubmit={handleSubmit} isLoading={mutation.isPending} />;
145}
146```
147 
148---
149 
150### 3. Error Handling
151 
152**Comprehensive error handling**:
153 
154```tsx
155class ApiError extends Error {
156  constructor(message: string, public status: number, public code?: string) {
157    super(message);
158    this.name = "ApiError";
159  }
160}
161 
162const fetchWithErrorHandling = async (url: string, options?: RequestInit) => {
163  try {
164    const response = await fetch(url, options);
165 
166    if (!response.ok) {
167      const error = await response.json().catch(() => ({}));
168      throw new ApiError(
169        error.message || "Request failed",
170        response.status,
171        error.code
172      );
173    }
174 
175    return response.json();
176  } catch (error) {
177    if (error instanceof ApiError) {
178      throw error;
179    }
180    // Network error (no internet, timeout, etc.)
181    throw new ApiError("Network error", 0, "NETWORK_ERROR");
182  }
183};
184```
185 
186**Retry logic**:
187 
188```tsx
189const fetchWithRetry = async (
190  url: string,
191  options?: RequestInit,
192  retries = 3
193) => {
194  for (let i = 0; i < retries; i++) {
195    try {
196      return await fetchWithErrorHandling(url, options);
197    } catch (error) {
198      if (i === retries - 1) throw error;
199      // Exponential backoff
200      await new Promise((r) => setTimeout(r, Math.pow(2, i) * 1000));
201    }
202  }
203};
204```
205 
206---
207 
208### 4. Authentication
209 
210**Token management**:
211 
212```tsx
213import * as SecureStore from "expo-secure-store";
214 
215const TOKEN_KEY = "auth_token";
216 
217export const auth = {
218  getToken: () => SecureStore.getItemAsync(TOKEN_KEY),
219  setToken: (token: string) => SecureStore.setItemAsync(TOKEN_KEY, token),
220  removeToken: () => SecureStore.deleteItemAsync(TOKEN_KEY),
221};
222 
223// Authenticated fetch wrapper
224const authFetch = async (url: string, options: RequestInit = {}) => {
225  const token = await auth.getToken();
226 
227  return fetch(url, {
228    ...options,
229    headers: {
230      ...options.headers,
231      Authorization: token ? `Bearer ${token}` : "",
232    },
233  });
234};
235```
236 
237**Token refresh**:
238 
239```tsx
240let isRefreshing = false;
241let refreshPromise: Promise<string> | null = null;
242 
243const getValidToken = async (): Promise<string> => {
244  const token = await auth.getToken();
245 
246  if (!token || isTokenExpired(token)) {
247    if (!isRefreshing) {
248      isRefreshing = true;
249      refreshPromise = refreshToken().finally(() => {
250        isRefreshing = false;
251        refreshPromise = null;
252      });
253    }
254    return refreshPromise!;
255  }
256 
257  return token;
258};
259```
260 
261---
262 
263### 5. Offline Support
264 
265**Check network status**:
266 
267```tsx
268import NetInfo from "@react-native-community/netinfo";
269 
270// Hook for network status
271function useNetworkStatus() {
272  const [isOnline, setIsOnline] = useState(true);
273 
274  useEffect(() => {
275    return NetInfo.addEventListener((state) => {
276      setIsOnline(state.isConnected ?? true);
277    });
278  }, []);
279 
280  return isOnline;
281}
282```
283 
284**Offline-first with React Query**:
285 
286```tsx
287import { onlineManager } from "@tanstack/react-query";
288import NetInfo from "@react-native-community/netinfo";
289 
290// Sync React Query with network status
291onlineManager.setEventListener((setOnline) => {
292  return NetInfo.addEventListener((state) => {
293    setOnline(state.isConnected ?? true);
294  });
295});
296 
297// Queries will pause when offline and resume when online
298```
299 
300---
301 
302### 6. Environment Variables
303 
304**Using environment variables for API configuration**:
305 
306Expo supports environment variables with the `EXPO_PUBLIC_` prefix. These are inlined at build time and available in your JavaScript code.
307 
308```tsx
309// .env
310EXPO_PUBLIC_API_URL=https://api.example.com
311EXPO_PUBLIC_API_VERSION=v1
312 
313// Usage in code
314const API_URL = process.env.EXPO_PUBLIC_API_URL;
315 
316const fetchUsers = async () => {
317  const response = await fetch(`${API_URL}/users`);
318  return response.json();
319};
320```
321 
322**Environment-specific configuration**:
323 
324```tsx
325// .env.development
326EXPO_PUBLIC_API_URL=http://localhost:3000
327 
328// .env.production
329EXPO_PUBLIC_API_URL=https://api.production.com
330```
331 
332**Creating an API client with environment config**:
333 
334```tsx
335// api/client.ts
336const BASE_URL = process.env.EXPO_PUBLIC_API_URL;
337 
338if (!BASE_URL) {
339  throw new Error("EXPO_PUBLIC_API_URL is not defined");
340}
341 
342export const apiClient = {
343  get: async <T,>(path: string): Promise<T> => {
344    const response = await fetch(`${BASE_URL}${path}`);
345    if (!response.ok) throw new Error(`HTTP ${response.status}`);
346    return response.json();
347  },
348 
349  post: async <T,>(path: string, body: unknown): Promise<T> => {
350    const response = await fetch(`${BASE_URL}${path}`, {
351      method: "POST",
352      headers: { "Content-Type": "application/json" },
353      body: JSON.stringify(body),
354    });
355    if (!response.ok) throw new Error(`HTTP ${response.status}`);
356    return response.json();
357  },
358};
359```
360 
361**Important notes**:
362 
363- Only variables prefixed with `EXPO_PUBLIC_` are exposed to the client bundle
364- Never put secrets (API keys with write access, database passwords) in `EXPO_PUBLIC_` variables—they're visible in the built app
365- Environment variables are inlined at **build time**, not runtime
366- Restart the dev server after changing `.env` files
367- For server-side secrets in API routes, use variables without the `EXPO_PUBLIC_` prefix
368 
369**TypeScript support**:
370 
371```tsx
372// types/env.d.ts
373declare global {
374  namespace NodeJS {
375    interface ProcessEnv {
376      EXPO_PUBLIC_API_URL: string;
377      EXPO_PUBLIC_API_VERSION?: string;
378    }
379  }
380}
381 
382export {};
383```
384 
385---
386 
387### 7. Request Cancellation
388 
389**Cancel on unmount**:
390 
391```tsx
392useEffect(() => {
393  const controller = new AbortController();
394 
395  fetch(url, { signal: controller.signal })
396    .then((response) => response.json())
397    .then(setData)
398    .catch((error) => {
399      if (error.name !== "AbortError") {
400        setError(error);
401      }
402    });
403 
404  return () => controller.abort();
405}, [url]);
406```
407 
408**With React Query** (automatic):
409 
410```tsx
411// React Query automatically cancels requests when queries are invalidated
412// or components unmount
413```
414 
415---
416 
417## Decision Tree
418 
419```
420User asks about networking
421  |-- Route-level data loading (web, SDK 55+)?
422  |   \-- Expo Router loaders — see references/expo-router-loaders.md
423  |
424  |-- Basic fetch?
425  |   \-- Use fetch API with error handling
426  |
427  |-- Need caching/state management?
428  |   |-- Complex app -> React Query (TanStack Query)
429  |   \-- Simpler needs -> SWR or custom hooks
430  |
431  |-- Authentication?
432  |   |-- Token storage -> expo-secure-store
433  |   \-- Token refresh -> Implement refresh flow
434  |
435  |-- Error handling?
436  |   |-- Network errors -> Check connectivity first
437  |   |-- HTTP errors -> Parse response, throw typed errors
438  |   \-- Retries -> Exponential backoff
439  |
440  |-- Offline support?
441  |   |-- Check status -> NetInfo
442  |   \-- Queue requests -> React Query persistence
443  |
444  |-- Environment/API config?
445  |   |-- Client-side URLs -> EXPO_PUBLIC_ prefix in .env
446  |   |-- Server secrets -> Non-prefixed env vars (API routes only)
447  |   \-- Multiple environments -> .env.development, .env.production
448  |
449  \-- Performance?
450      |-- Caching -> React Query with staleTime
451      |-- Deduplication -> React Query handles this
452      \-- Cancellation -> AbortController or React Query
453```
454 
455## Common Mistakes
456 
457**Wrong: No error handling**
458 
459```tsx
460const data = await fetch(url).then((r) => r.json());
461```
462 
463**Right: Check response status**
464 
465```tsx
466const response = await fetch(url);
467if (!response.ok) throw new Error(`HTTP ${response.status}`);
468const data = await response.json();
469```
470 
471**Wrong: Storing tokens in AsyncStorage**
472 
473```tsx
474await AsyncStorage.setItem("token", token); // Not secure!
475```
476 
477**Right: Use SecureStore for sensitive data**
478 
479```tsx
480await SecureStore.setItemAsync("token", token);
481```
482 
483## Example Invocations
484 
485User: "How do I make API calls in React Native?"
486-> Use fetch, wrap with error handling
487 
488User: "Should I use React Query or SWR?"
489-> React Query for complex apps, SWR for simpler needs
490 
491User: "My app needs to work offline"
492-> Use NetInfo for status, React Query persistence for caching
493 
494User: "How do I handle authentication tokens?"
495-> Store in expo-secure-store, implement refresh flow
496 
497User: "API calls are slow"
498-> Check caching strategy, use React Query staleTime
499 
500User: "How do I configure different API URLs for dev and prod?"
501-> Use EXPO*PUBLIC* env vars with .env.development and .env.production files
502 
503User: "Where should I put my API key?"
504-> Client-safe keys: EXPO*PUBLIC* in .env. Secret keys: non-prefixed env vars in API routes only
505 
506User: "How do I load data for a page in Expo Router?"
507-> See references/expo-router-loaders.md for route-level loaders (web, SDK 55+). For native, use React Query or fetch.
508