@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/domain/expo-native-ui/references/data-fetching.md

@@ -0,0 +1,553 @@
+# Expo Networking
+
+**You MUST use this skill for ANY networking work including API requests, data fetching, caching, or network debugging.**
+
+## References
+
+Consult these resources as needed:
+
+```
+references/
+  expo-router-loaders.md   Route-level data loading with Expo Router loaders (web, SDK 55+)
+```
+
+## When to Use
+
+Use this skill when:
+
+- Implementing API requests
+- Setting up data fetching (React Query, SWR)
+- Using Expo Router data loaders (`useLoaderData`, web SDK 55+)
+- Debugging network failures
+- Implementing caching strategies
+- Handling offline scenarios
+- Authentication/token management
+- Configuring API URLs and environment variables
+
+## Preferences
+
+- Avoid axios, prefer expo/fetch
+
+## Common Issues & Solutions
+
+### 1. Basic Fetch Usage
+
+**Simple GET request**:
+
+```tsx
+const fetchUser = async (userId: string) => {
+  const response = await fetch(`https://api.example.com/users/${userId}`);
+
+  if (!response.ok) {
+    throw new Error(`HTTP error! status: ${response.status}`);
+  }
+
+  return response.json();
+};
+```
+
+**POST request with body**:
+
+```tsx
+const createUser = async (userData: UserData) => {
+  const response = await fetch("https://api.example.com/users", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify(userData),
+  });
+
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.message);
+  }
+
+  return response.json();
+};
+```
+
+### 3. Error Handling
+
+**Comprehensive error handling**:
+
+```tsx
+class ApiError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public code?: string,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+const fetchWithErrorHandling = async (url: string, options?: RequestInit) => {
+  try {
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new ApiError(
+        error.message || "Request failed",
+        response.status,
+        error.code,
+      );
+    }
+
+    return response.json();
+  } catch (error) {
+    if (error instanceof ApiError) {
+      throw error;
+    }
+    // Network error (no internet, timeout, etc.)
+    throw new ApiError("Network error", 0, "NETWORK_ERROR");
+  }
+};
+```
+
+**Retry logic**:
+
+```tsx
+const fetchWithRetry = async (
+  url: string,
+  options?: RequestInit,
+  retries = 3,
+) => {
+  for (let i = 0; i < retries; i++) {
+    try {
+      return await fetchWithErrorHandling(url, options);
+    } catch (error) {
+      if (i === retries - 1) throw error;
+      // Exponential backoff
+      await new Promise((r) => setTimeout(r, Math.pow(2, i) * 1000));
+    }
+  }
+};
+```
+
+### 5. Offline Support
+
+**Check network status**:
+
+```tsx
+import NetInfo from "@react-native-community/netinfo";
+
+// Hook for network status
+function useNetworkStatus() {
+  const [isOnline, setIsOnline] = useState(true);
+
+  useEffect(() => {
+    return NetInfo.addEventListener((state) => {
+      setIsOnline(state.isConnected ?? true);
+    });
+  }, []);
+
+  return isOnline;
+}
+```
+
+**Offline-first with React Query**:
+
+```tsx
+import { onlineManager } from "@tanstack/react-query";
+import NetInfo from "@react-native-community/netinfo";
+
+// Sync React Query with network status
+onlineManager.setEventListener((setOnline) => {
+  return NetInfo.addEventListener((state) => {
+    setOnline(state.isConnected ?? true);
+  });
+});
+
+// Queries will pause when offline and resume when online
+```
+
+### 7. Request Cancellation
+
+**Cancel on unmount**:
+
+```tsx
+useEffect(() => {
+  const controller = new AbortController();
+
+  fetch(url, { signal: controller.signal })
+    .then((response) => response.json())
+    .then(setData)
+    .catch((error) => {
+      if (error.name !== "AbortError") {
+        setError(error);
+      }
+    });
+
+  return () => controller.abort();
+}, [url]);
+```
+
+**With React Query** (automatic):
+
+```tsx
+// React Query automatically cancels requests when queries are invalidated
+// or components unmount
+```
+
+---
+
+# Expo Router Data Loaders
+
+Route-level data loading for web apps using Expo SDK 55+. Loaders are async functions exported from route files that load data before the route renders, following the Remix/React Router loader model.
+
+**Dual execution model:**
+
+- **Initial page load (SSR):** The loader runs server-side. Its return value is serialized as JSON and embedded in the HTML response.
+- **Client-side navigation:** The browser fetches the loader data from the server via HTTP. The route renders once the data arrives.
+
+You write one function and the framework manages when and how it executes.
+
+## Configuration
+
+**Requirements:** Expo SDK 55+, web output mode (`npx expo serve` or `npx expo export --platform web`) set in `app.json` or `app.config.js`.
+
+**Server rendering:**
+
+```json
+{
+  "expo": {
+    "web": {
+      "output": "server"
+    },
+    "plugins": [
+      [
+        "expo-router",
+        {
+          "unstable_useServerDataLoaders": true,
+          "unstable_useServerRendering": true
+        }
+      ]
+    ]
+  }
+}
+```
+
+**Static/SSG:**
+
+```json
+{
+  "expo": {
+    "web": {
+      "output": "static"
+    },
+    "plugins": [
+      [
+        "expo-router",
+        {
+          "unstable_useServerDataLoaders": true
+        }
+      ]
+    ]
+  }
+}
+```
+
+|                                 | `"server"`                     | `"static"`                            |
+| ------------------------------- | ------------------------------ | ------------------------------------- |
+| `unstable_useServerDataLoaders` | Required                       | Required                              |
+| `unstable_useServerRendering`   | Required                       | Not required                          |
+| Loader runs on                  | Live server (every request)    | Build time (static generation)        |
+| `request` object                | Full access (headers, cookies) | Not available                         |
+| Hosting                         | Node.js server (EAS Hosting)   | Any static host (Netlify, Vercel, S3) |
+
+## Imports
+
+Loaders use two packages:
+
+- **`expo-router`** — `useLoaderData` hook
+- **`expo-server`** — `LoaderFunction` type, `StatusError`, `setResponseHeaders`. Always available (dependency of `expo-router`), no install needed.
+
+## Basic Loader
+
+For loaders without params, a plain async function works:
+
+```tsx
+// app/posts/index.tsx
+import { Suspense } from "react";
+import { useLoaderData } from "expo-router";
+import { ActivityIndicator, View, Text } from "react-native";
+
+export async function loader() {
+  const response = await fetch("https://api.example.com/posts");
+  const posts = await response.json();
+  return { posts };
+}
+
+function PostList() {
+  const { posts } = useLoaderData<typeof loader>();
+
+  return (
+    <View>
+      {posts.map((post) => (
+        <Text key={post.id}>{post.title}</Text>
+      ))}
+    </View>
+  );
+}
+
+export default function Posts() {
+  return (
+    <Suspense fallback={<ActivityIndicator size="large" />}>
+      <PostList />
+    </Suspense>
+  );
+}
+```
+
+`useLoaderData` is typed via `typeof loader` — the generic parameter infers the return type.
+
+## Dynamic Routes
+
+For loaders with params, use the `LoaderFunction<T>` type from `expo-server`. The first argument is the request (an immutable `Request`-like object, or `undefined` in static mode). The second is `params` (`Record<string, string | string[]>`), which contains **path parameters only**. Access individual params with a cast like `params.id as string`. For query parameters, use `new URL(request.url).searchParams`:
+
+```tsx
+// app/posts/[id].tsx
+import { Suspense } from "react";
+import { useLoaderData } from "expo-router";
+import { StatusError, type LoaderFunction } from "expo-server";
+import { ActivityIndicator, View, Text } from "react-native";
+
+type Post = {
+  id: number;
+  title: string;
+  body: string;
+};
+
+export const loader: LoaderFunction<{ post: Post }> = async (
+  request,
+  params,
+) => {
+  const id = params.id as string;
+  const response = await fetch(`https://api.example.com/posts/${id}`);
+
+  if (!response.ok) {
+    throw new StatusError(404, `Post ${id} not found`);
+  }
+
+  const post: Post = await response.json();
+  return { post };
+};
+
+function PostContent() {
+  const { post } = useLoaderData<typeof loader>();
+
+  return (
+    <View>
+      <Text>{post.title}</Text>
+      <Text>{post.body}</Text>
+    </View>
+  );
+}
+
+export default function PostDetail() {
+  return (
+    <Suspense fallback={<ActivityIndicator size="large" />}>
+      <PostContent />
+    </Suspense>
+  );
+}
+```
+
+Catch-all routes access `params.slug` the same way:
+
+```tsx
+// app/docs/[...slug].tsx
+import { type LoaderFunction } from "expo-server";
+
+type Doc = { title: string; content: string };
+
+export const loader: LoaderFunction<{ doc: Doc }> = async (request, params) => {
+  const slug = params.slug as string[];
+  const path = slug.join("/");
+  const doc = await fetchDoc(path);
+  return { doc };
+};
+```
+
+Query parameters are available via the `request` object (server output mode only):
+
+```tsx
+// app/search.tsx
+import { type LoaderFunction } from "expo-server";
+
+export const loader: LoaderFunction<{ results: any[]; query: string }> = async (
+  request,
+) => {
+  // Assuming request.url is `/search?q=expo&page=2`
+  const url = new URL(request!.url);
+  const query = url.searchParams.get("q") ?? "";
+  const page = Number(url.searchParams.get("page") ?? "1");
+
+  const results = await fetchSearchResults(query, page);
+  return { results, query };
+};
+```
+
+## Server-Side Secrets & Request Access
+
+Loaders run on the server, so you can access secrets and server-only resources directly:
+
+```tsx
+// app/dashboard.tsx
+import { type LoaderFunction } from "expo-server";
+
+export const loader: LoaderFunction<{
+  balance: any;
+  isAuthenticated: boolean;
+}> = async (request, params) => {
+  const data = await fetch("https://api.stripe.com/v1/balance", {
+    headers: {
+      Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
+    },
+  });
+
+  const sessionToken = request?.headers
+    .get("cookie")
+    ?.match(/session=([^;]+)/)?.[1];
+
+  const balance = await data.json();
+  return { balance, isAuthenticated: !!sessionToken };
+};
+```
+
+The `request` object is available in server output mode. In static output mode, `request` is always `undefined`.
+
+## Response Utilities
+
+### Setting Response Headers
+
+```tsx
+// app/products.tsx
+import { setResponseHeaders } from "expo-server";
+
+export async function loader() {
+  setResponseHeaders({
+    "Cache-Control": "public, max-age=300",
+  });
+
+  const products = await fetchProducts();
+  return { products };
+}
+```
+
+### Throwing HTTP Errors
+
+```tsx
+// app/products/[id].tsx
+import { StatusError, type LoaderFunction } from "expo-server";
+
+export const loader: LoaderFunction<{ product: Product }> = async (
+  request,
+  params,
+) => {
+  const id = params.id as string;
+  const product = await fetchProduct(id);
+
+  if (!product) {
+    throw new StatusError(404, "Product not found");
+  }
+
+  return { product };
+};
+```
+
+## Suspense & Error Boundaries
+
+### Loading States with Suspense
+
+`useLoaderData()` suspends during client-side navigation. Push it into a child component and wrap with `<Suspense>`:
+
+```tsx
+// app/posts/index.tsx
+import { Suspense } from "react";
+import { useLoaderData } from "expo-router";
+import { ActivityIndicator, View, Text } from "react-native";
+
+export async function loader() {
+  const response = await fetch("https://api.example.com/posts");
+  return { posts: await response.json() };
+}
+
+function PostList() {
+  const { posts } = useLoaderData<typeof loader>();
+
+  return (
+    <View>
+      {posts.map((post) => (
+        <Text key={post.id}>{post.title}</Text>
+      ))}
+    </View>
+  );
+}
+
+export default function Posts() {
+  return (
+    <Suspense
+      fallback={
+        <View
+          style={{ flex: 1, justifyContent: "center", alignItems: "center" }}
+        >
+          <ActivityIndicator size="large" />
+        </View>
+      }
+    >
+      <PostList />
+    </Suspense>
+  );
+}
+```
+
+The `<Suspense>` boundary must be above the component calling `useLoaderData()`. On initial page load the data is already in the HTML, suspension only occurs during client-side navigation.
+
+### Error Boundaries
+
+```tsx
+// app/posts/[id].tsx
+export function ErrorBoundary({ error }: { error: Error }) {
+  return (
+    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
+      <Text>Error: {error.message}</Text>
+    </View>
+  );
+}
+```
+
+When a loader throws (including `StatusError`), the nearest `ErrorBoundary` catches it.
+
+## Static vs Server Rendering
+
+|                      | Server (`"server"`)             | Static (`"static"`)               |
+| -------------------- | ------------------------------- | --------------------------------- |
+| **When loader runs** | Every request (live)            | At build time (`npx expo export`) |
+| **Data freshness**   | Fresh on initial server request | Stale until next build            |
+| **`request` object** | Full access                     | Not available                     |
+| **Hosting**          | Node.js server (EAS Hosting)    | Any static host                   |
+| **Use case**         | Personalized/dynamic content    | Marketing pages, blogs, docs      |
+
+**Choose server** when data changes frequently or content is personalized (cookies, auth, headers).
+
+**Choose static** when content is the same for all users and changes infrequently.
+
+## Best Practices
+
+- Loaders are web-only; use client-side fetching (React Query, fetch) for native
+- Loaders cannot be used in `_layout` files — only in route files
+- Use `LoaderFunction<T>` from `expo-server` to type loaders that use params
+- The request object is immutable — use optional chaining (`request?.headers`) as it may be `undefined` in static mode
+- Return only JSON-serializable values (no `Date`, `Map`, `Set`, class instances, functions)
+- Use non-prefixed `process.env` vars for secrets in loaders, not `EXPO_PUBLIC_` (which is embedded in the client bundle)
+- Use `StatusError` from `expo-server` for HTTP error responses
+- Use `setResponseHeaders` from `expo-server` to set headers
+- Export `ErrorBoundary` from route files to handle loader failures gracefully
+- Validate and sanitize user input (params, query strings) before using in database queries or API calls
+- Handle errors gracefully with try/catch; log server-side for debugging
+- Loader data is currently cached for the session. This is a known limitation that will be lifted in a future release