State Management Basics

npx create-expo-app@latest MyApp --template default@sdk-57
cd MyApp
npm install

{
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

npx expo install @tanstack/react-query @react-native-community/netinfo

// app/(tabs)/catalog/index.tsx
import { useState } from "react";
import { Modal, Pressable, Text, View } from "react-native";
 
export default function CatalogScreen() {
  const [filterOpen, setFilterOpen] = useState(false);
 
  return (
    <View style={{ flex: 1, padding: 16 }}>
      <Pressable onPress={() => setFilterOpen(true)}>
        <Text>Filters</Text>
      </Pressable>
 
      <Modal visible={filterOpen} animationType="slide" onRequestClose={() => setFilterOpen(false)}>
        <View style={{ flex: 1, padding: 24 }}>
          <Text>Filter sheet - local state only</Text>
          <Pressable onPress={() => setFilterOpen(false)}>
            <Text>Close</Text>
          </Pressable>
        </View>
      </Modal>
    </View>
  );
}

// src/features/catalog/components/ProductRow.tsx
import { Pressable, Text, View } from "react-native";
 
type Props = {
  title: string;
  priceLabel: string;
  selected: boolean;
  onPress: () => void;
};
 
export function ProductRow({ title, priceLabel, selected, onPress }: Props) {
  return (
    <Pressable onPress={onPress} style={{ padding: 12, backgroundColor: selected ? "#e0f2fe" : "#fff" }}>
      <Text style={{ fontWeight: "600" }}>{title}</Text>
      <Text>{priceLabel}</Text>
    </Pressable>
  );
}

// Parent owns selection state
import { useState } from "react";
import { FlatList } from "react-native";
import { ProductRow } from "@/features/catalog/components/ProductRow";
 
const PRODUCTS = [
  { id: "1", title: "Trail Pack", priceLabel: "$89" },
  { id: "2", title: "Day Pack", priceLabel: "$49" },
];
 
export function ProductList() {
  const [selectedId, setSelectedId] = useState<string | null>(null);
 
  return (
    <FlatList
      data={PRODUCTS}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <ProductRow
          title={item.title}
          priceLabel={item.priceLabel}
          selected={selectedId === item.id}
          onPress={() => setSelectedId(item.id)}
        />
      )}
    />
  );
}

// ❌ Anti-pattern - API data in useState with manual useEffect
const [orders, setOrders] = useState<Order[]>([]);
const [loading, setLoading] = useState(true);
 
useEffect(() => {
  fetch("/orders")
    .then((r) => r.json())
    .then(setOrders)
    .finally(() => setLoading(false));
}, []);

// ✅ Server state in TanStack Query; client state stays local
import { useQuery } from "@tanstack/react-query";
import { useState } from "react";
 
function OrdersScreen() {
  const [sort, setSort] = useState<"newest" | "oldest">("newest");
 
  const { data: orders = [], isPending, isError, refetch } = useQuery({
    queryKey: ["orders"],
    queryFn: fetchOrders,
    staleTime: 60_000,
  });
 
  const sorted = [...orders].sort((a, b) =>
    sort === "newest" ? b.placedAt.localeCompare(a.placedAt) : a.placedAt.localeCompare(b.placedAt)
  );
 
  // render sorted, isPending, isError, refetch, setSort...
}

// src/features/cart/useCartStore.ts
import { create } from "zustand";
 
type CartItem = { productId: string; qty: number };
 
type CartStore = {
  items: CartItem[];
  add: (item: CartItem) => void;
  count: () => number;
};
 
export const useCartStore = create<CartStore>((set, get) => ({
  items: [],
  add: (item) => set((s) => ({ items: [...s.items, item] })),
  count: () => get().items.reduce((n, i) => n + i.qty, 0),
}));

// Tab bar reads count via selector - not the whole store
import { useCartStore } from "@/features/cart/useCartStore";
import { Text, View } from "react-native";
 
export function CartTabIcon() {
  const count = useCartStore((s) => s.count());
  return (
    <View>
      <Text>Cart</Text>
      {count > 0 && <Text>{count}</Text>}
    </View>
  );
}

// app/(tabs)/catalog/index.tsx
import { router, useLocalSearchParams } from "expo-router";
import { Pressable, Text, View } from "react-native";
 
type Params = { category?: string };
 
export default function CatalogRoute() {
  const { category = "all" } = useLocalSearchParams<Params>();
 
  return (
    <View style={{ padding: 16, gap: 8 }}>
      <Text>Category: {category}</Text>
      {(["all", "gear", "apparel"] as const).map((c) => (
        <Pressable key={c} onPress={() => router.setParams({ category: c })}>
          <Text style={{ fontWeight: category === c ? "700" : "400" }}>{c}</Text>
        </Pressable>
      ))}
    </View>
  );
}

import NetInfo from "@react-native-community/netinfo";
import { onlineManager, useQuery } from "@tanstack/react-query";
import { useEffect } from "react";
import { Text, View } from "react-native";
 
onlineManager.setEventListener((setOnline) =>
  NetInfo.addEventListener((state) => setOnline(!!state.isConnected))
);
 
function ProductList() {
  const { data, isPending, isFetching, isError } = useQuery({
    queryKey: ["products"],
    queryFn: fetchProducts,
    staleTime: 5 * 60_000,
    gcTime: 24 * 60 * 60_000,
    retry: 2,
  });
 
  const showOfflineCache = !isPending && data && isError;
 
  return (
    <View>
      {showOfflineCache && <Text>Offline - showing saved results</Text>}
      {isFetching && !isPending && <Text>Updating…</Text>}
      {/* render data */}
    </View>
  );
}

// app/_layout.tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { Stack } from "expo-router";
import { useState } from "react";
import { SessionProvider } from "@/features/auth/SessionProvider";
 
export default function RootLayout() {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: { staleTime: 30_000, retry: 2 },
        },
      })
  );
 
  return (
    <QueryClientProvider client={queryClient}>
      <SessionProvider>
        <Stack screenOptions={{ headerShown: false }} />
      </SessionProvider>
    </QueryClientProvider>
  );
}

import { useQuery } from "@tanstack/react-query";
import { useState } from "react";
import { useCartStore } from "@/features/cart/useCartStore";
 
export function CheckoutScreen() {
  const items = useCartStore((s) => s.items);
  const [shippingId, setShippingId] = useState<string | null>(null);
 
  const { data: methods = [], isPending } = useQuery({
    queryKey: ["shipping-methods", items.length],
    queryFn: () => fetchShippingMethods(items),
    enabled: items.length > 0,
  });
 
  // UI: cart summary from Zustand, methods from Query, selection from useState
}

// src/lib/queryPersister.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import { createAsyncStoragePersister } from "@tanstack/query-async-storage-persister";
 
export const asyncStoragePersister = createAsyncStoragePersister({
  storage: AsyncStorage,
  key: "REACT_QUERY_OFFLINE_CACHE",
});

// app/_layout.tsx (excerpt)
import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
import { asyncStoragePersister } from "@/lib/queryPersister";
 
<PersistQueryClientProvider
  client={queryClient}
  persistOptions={{ persister: asyncStoragePersister, maxAge: 1000 * 60 * 60 * 24 }}
>
  {children}
</PersistQueryClientProvider>

npx expo install @react-native-async-storage/async-storage @tanstack/react-query-persist-client @tanstack/query-async-storage-persister

State checklist (answer before npm install):
 
1. Is it from an API?           → TanStack Query (or RTK Query if Redux already)
2. Is it shareable in a URL?    → Expo Router search params
3. Is it a multi-field form?    → React Hook Form + mutation on submit
4. Is it global client UI?      → Zustand or split Context
5. Is it ephemeral on one screen? → useState / useReducer
6. Is it a secret token?        → expo-secure-store + thin SessionProvider
7. Does compliance need audit?  → Redux Toolkit + DevTools
 
If two libraries answer the same "yes" - pick one and document in an ADR.

// Document the team default in a comment or ADR link at the store boundary
/** @see docs/adr-state-management - server: Query, client: Zustand, URL: Router */
export const usePreferences = create<PreferencesStore>(/* ... */);