rn-backend

rn-backend — provider-agnostic backend integration for RN/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, regardless of provider)

1. Tokens in expo-secure-store, never AsyncStorage or plain in-memory. Tokens are bearer credentials — they go in Keychain (iOS) / Keystore (Android) encrypted at rest.
2. Auth state in a Zustand store + replicated in TanStack Query with key ["auth", "session"]. Zustand for synchronous reads in components and _layout.tsx redirect logic; TanStack Query for refetch-on-focus and revalidation.
3. api() wrapper owns auth headers + refresh-on-401. Every fetch goes through it. Refresh flow is centralized — no per-call retry logic.
4. Auth gate via Expo Router groups: (auth)/ for public screens, (app)/ for protected; the (app)/_layout.tsx checks the store and <Redirect /> if no user.
5. Sign-out clears EVERYTHING: secure-store token, Zustand store, TanStack Query cache (queryClient.clear()). No "user signed out but still see old data" bugs.

Quick decision tree

• "Which provider? Supabase / Firebase / custom REST / tRPC?" → references/decision-tree.md
• "What's the shared client-auth architecture?" → references/concepts.md
• "How do I wire it up — store, middleware, gate?" → references/patterns.md
• "I picked Supabase. Specifics?" → references/supabase.md
• "I picked Firebase." → references/firebase.md
• "I'm bringing my own REST/JSON backend." → references/custom-rest.md
• "I want tRPC end-to-end typed." → references/trpc.md

Common anti-patterns (NEVER do)

• ❌ AsyncStorage.setItem("token", token) — use SecureStore.setItemAsync("token", token).
• ❌ Reading the token inside every api() call from secure-store synchronously — cache it in the Zustand store, refresh from secure-store only on app start.
• ❌ Stored "logged in" boolean in the client that drifts from the server token's actual validity — single source of truth is the token + a /me query.
• ❌ Calling signOut() and forgetting to queryClient.clear() — next user sees previous user's posts in cache.
• ❌ Hardcoding Authorization: Bearer xxx in a single screen — wrap in api().
• ❌ Vendor lock-in code scattered (supabase.auth.signIn(...) in 12 components) — wrap in lib/auth.ts so swapping providers touches one file.