Rn Backend

---
name: rn-backend
description: 'Use to connect an Expo + RN app to a backend (auth, database, storage, realtime), agnostic of the provider. Teaches the shared patterns: secure-store for tokens, auth state via Zustand + TanStack Query, refresh-on-401 middleware, auth-gate routing via Expo Router (app)/_layout.tsx, row-level security vs API-auth concepts. Provider-specific details live in sub-references: Supabase (default, matches the course), Firebase, custom REST/JSON, tRPC. Triggers on: "setup backend", "setup auth with X", "connect Supabase/Firebase/my API", "secure token storage", "refresh token flow", "row level security". Not for: building the login UI (rn-add-screen — uses Form template), push notifications (rn-push-notifications), payments (rn-publishing-payments).'
---

# 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.

## Sources

- Course: codewithbeto.dev/rnCourse — "Backend Basics" + "Supabase" modules (paid).
- Official Supabase: https://supabase.com/docs/reference/javascript/auth-signinwithpassword
- Official Firebase: https://firebase.google.com/docs/auth/web/start
- Official tRPC: https://trpc.io/docs/client/react/server-components
- Official secure-store: https://docs.expo.dev/versions/latest/sdk/securestore/