Noções Básicas de Gerenciamento de Estado

10 exemplos para você começar com Gerenciamento de Estado - 7 básicos e 3 intermediários. Usuários de dispositivos móveis perdem sinal constantemente; classifique o estado antes de escolher uma biblioteca.

Pré-requisitos

Crie um aplicativo Expo com formato de produção e um pin explícito do SDK 57. Os exemplos de estado assumem Expo Router e TypeScript.

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

Confirme o pin do SDK antes de adicionar bibliotecas de estado:

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

Instale a camada padrão de estado do servidor que a maioria das equipes adota desde o primeiro dia:

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

Ferramentas: Estes exemplos visam o Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3.

Exemplos Básicos

1. Estado Local para UI Efêmera

Modal aberto, aba expandida, índice de aba pressionado - estado que morre quando a tela é desmontada pertence ao useState dessa tela.

// 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>Filtros</Text>
      </Pressable>
 
      <Modal visible={filterOpen} animationType="slide" onRequestClose={() => setFilterOpen(false)}>
        <View style={{ flex: 1, padding: 24 }}>
          <Text>Aba de filtros - apenas estado local</Text>
          <Pressable onPress={() => setFilterOpen(false)}>
            <Text>Fechar</Text>
          </Pressable>
        </View>
      </Modal>
    </View>
  );
}

filterOpen não precisa de Redux, Zustand ou Context - nenhuma outra tela o lê
Desmontar a tela redefine o estado automaticamente - sem limpeza manual
Se três componentes irmãos na mesma tela precisarem dele, eleve o estado para um pai ou um hook de nível de tela - ainda não é global

Relacionado: useState & useReducer - quando o estado local excede uma única tela

2. Props vs. Estado Próprio

Props fluem para baixo; estado é de propriedade do componente que o atualiza. Itens de lista de dispositivos móveis devem permanecer apresentacionais.

// 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>
  );
}

// O pai é o dono do estado de seleção
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)}
        />
      )}
    />
  );
}

ProductRow não tem useState - re-renderiza apenas quando as props mudam
O selectedId do pai é a única fonte de verdade para o estado de destaque
Passar onPress mantém a navegação e os efeitos colaterais na camada do container

Relacionado: ../component-patterns/container-presenter-on-mobile/container-presenter-on-mobile.md - separando hooks de dados de JSX

3. Estado do Servidor vs. Estado do Cliente

Estado do servidor vem de uma API e fica desatualizado. Estado do cliente é a UI que o usuário controla. Misturá-los em um único blob useState causa bugs de re-fetch.

// ❌ Anti-padrão - dados da API em useState com useEffect manual
const [orders, setOrders] = useState<Order[]>([]);
const [loading, setLoading] = useState(true);
 
useEffect(() => {
  fetch("/orders")
    .then((r) => r.json())
    .then(setOrders)
    .finally(() => setLoading(false));
}, []);

// ✅ Estado do servidor no TanStack Query; estado do cliente permanece 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)
  );
 
  // renderizar sorted, isPending, isError, refetch, setSort...
}

orders são de propriedade do servidor - cache, deduplicação e atualização em segundo plano pertencem ao Query
sort é de propriedade do cliente - sem ida e volta à rede quando o usuário alterna
Puxar para atualizar chama refetch() - não um setOrders manual

Relacionado: TanStack Query - políticas de cache para dispositivos móveis | ../architecture-design/adr-state-management-selection/adr-state-management-selection.md - matriz de decisão

4. Estado Global do Cliente (Quando Telas o Compartilham)

Badge do carrinho, modo de tema, conclusão do onboarding - estado que sobrevive à navegação mas não são dados de API se encaixam em um pequeno store global ou Context dividido.

// 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),
}));

// A barra de abas lê a contagem via seletor - não o store inteiro
import { useCartStore } from "@/features/cart/useCartStore";
import { Text, View } from "react-native";
 
export function CartTabIcon() {
  const count = useCartStore((s) => s.count());
  return (
    <View>
      <Text>Carrinho</Text>
      {count > 0 && <Text>{count}</Text>}
    </View>
  );
}

Seletores do Zustand limitam re-renderizações - o ícone da aba atualiza sem re-renderizar a lista do catálogo
Não coloque o catálogo de produtos buscado neste store - isso é estado do servidor
Instale com npx expo install zustand - JS puro, sem módulo nativo

Relacionado: Zustand - slices, devtools e testes

5. Estado da URL com Expo Router

Filtros, abas e paginação que devem ser restaurados em deep links pertencem aos parâmetros de pesquisa da rota - não a um store global.

// 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>Categoria: {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>
  );
}

useLocalSearchParams lê a string de consulta equivalente da rota atual
router.setParams atualiza os parâmetros sem perder a posição da pilha - o botão voltar do sistema operacional restaura o filtro anterior
Links compartilháveis (myapp://catalog?category=gear) funcionam quando scheme é definido em app.config.ts

Relacionado: Rotas Tipadas - parâmetros tipados no SDK 57

6. Redes Intermitentes e Dados Desatualizados

Em dispositivos móveis, assuma que o usuário está offline em um elevador. Mostre os últimos dados válidos com um banner offline sutil - não uma tela em branco.

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 - mostrando resultados salvos</Text>}
      {isFetching && !isPending && <Text>Atualizando…</Text>}
      {/* renderizar dados */}
    </View>
  );
}

staleTime mantém os dados em cache visíveis enquanto uma re-busca em segundo plano é executada
onlineManager informa ao Query quando o dispositivo se reconecta - aciona refetchOnReconnect
gcTime (anteriormente cacheTime) controla quanto tempo o cache não utilizado sobrevive na memória

Relacionado: TanStack Query - focusManager no AppState | ../error-resilience/network-failure-ux/network-failure-ux.md - padrões de UX offline

7. Árvore de Providers Raiz (Mínima)

Conecte provedores de estado do servidor e de sessão uma vez em app/_layout.tsx - evite aninhar provedores por tela.

// 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>
  );
}

QueryClient é criado uma vez por sessão do aplicativo - useState(() => new QueryClient()) evita compartilhamento acidental entre testes e produção no mesmo módulo
SessionProvider expõe a identidade de autenticação - tokens vivem no expo-secure-store, não no cache do Query
Mantenha a árvore plana - aninhamento profundo de provedores retarda o início a frio e complica os testes

Relacionado: Context Without Storms - divida contextos quando os provedores re-renderizam demais

Exemplos Intermediários

8. Dividindo Estado do Servidor e do Cliente em Uma Tela

Uma tela de checkout combina carrinho (cliente), opções de frete (servidor) e método selecionado (cliente). Três baldes, três ferramentas.

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: resumo do carrinho do Zustand, métodos do Query, seleção do useState
}

Itens do carrinho são globais do cliente (Zustand) - o usuário os adicionou em várias telas
Métodos de frete dependem do conteúdo do carrinho - a chave do Query inclui items.length para invalidação
shippingId é UI efêmera nesta tela - useState até o envio, depois mutação

Relacionado: ../architecture-design/clean-architecture-on-mobile/clean-architecture-on-mobile.md - casos de uso vs. hooks

9. Último Dado Válido Conhecido no Início a Frio

Persista o cache do Query no AsyncStorage para que as telas de catálogo renderizem imediatamente após o encerramento do processo - hidrate antes da primeira pintura, quando possível.

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

// app/_layout.tsx (trecho)
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

maxAge limita a idade do cache persistido - combine com staleTime por consulta
Mostre um gate de hidratação ou esqueleto apenas quando não houver dados persistidos - veja o guia de persistência
Logout deve chamar queryClient.clear() e limpar o persister - dados de usuário desatualizados são um bug de segurança

Relacionado: Persistência e Hidratação de Estado - início a frio sem travamentos

10. Checklist de Decisão Antes de Adicionar uma Biblioteca

Execute este checklist quando um colega propuser Redux, Jotai ou outro store.

Checklist de estado (responda antes de npm install):
 
1. É de uma API?           → TanStack Query (ou RTK Query se já usar Redux)
2. É compartilhável em uma URL?    → Parâmetros de pesquisa do Expo Router
3. É um formulário com múltiplos campos?    → React Hook Form + mutação no submit
4. É UI global do cliente?      → Zustand ou Context dividido
5. É efêmero em uma tela? → useState / useReducer
6. É um token secreto?        → expo-secure-store + SessionProvider fino
7. A conformidade precisa de auditoria?  → Redux Toolkit + DevTools
 
Se duas bibliotecas responderem "sim" à mesma pergunta - escolha uma e documente em um ADR.

// Documente o padrão da equipe em um comentário ou link ADR no limite do store
/** @see docs/adr-state-management - servidor: Query, cliente: Zustand, URL: Router */
export const usePreferences = create<PreferencesStore>(/* ... */);

Sete perguntas evitam a instalação de três stores globais sobrepostos
Novas equipes devem ler o ADR antes de introduzir MobX, Jotai ou um segundo wrapper do Query
Reavalie quando os requisitos mudarem - sincronização offline, edição colaborativa ou DevTools obrigatórios

Relacionado: ../architecture-design/adr-state-management-selection/adr-state-management-selection.md - decisões classificadas | Melhores Práticas - resumo da seção

Versões da pilha: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Pré-requisitos

Crie um aplicativo Expo com formato de produção e um pin explícito do SDK 57. Os exemplos de estado assumem Expo Router e TypeScript.

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

Confirme o pin do SDK antes de adicionar bibliotecas de estado:

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

Instale a camada padrão de estado do servidor que a maioria das equipes adota desde o primeiro dia:

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

Ferramentas: Estes exemplos visam o Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3.

Exemplos Básicos

1. Estado Local para UI Efêmera

Modal aberto, aba expandida, índice de aba pressionado - estado que morre quando a tela é desmontada pertence ao useState dessa tela.

// 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>Filtros</Text>
      </Pressable>
 
      <Modal visible={filterOpen} animationType="slide" onRequestClose={() => setFilterOpen(false)}>
        <View style={{ flex: 1, padding: 24 }}>
          <Text>Aba de filtros - apenas estado local</Text>
          <Pressable onPress={() => setFilterOpen(false)}>
            <Text>Fechar</Text>
          </Pressable>
        </View>
      </Modal>
    </View>
  );
}

filterOpen não precisa de Redux, Zustand ou Context - nenhuma outra tela o lê
Desmontar a tela redefine o estado automaticamente - sem limpeza manual
Se três componentes irmãos na mesma tela precisarem dele, eleve o estado para um pai ou um hook de nível de tela - ainda não é global

Relacionado: useState & useReducer - quando o estado local excede uma única tela

2. Props vs. Estado Próprio

Props fluem para baixo; estado é de propriedade do componente que o atualiza. Itens de lista de dispositivos móveis devem permanecer apresentacionais.

// 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>
  );
}

// O pai é o dono do estado de seleção
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)}
        />
      )}
    />
  );
}

ProductRow não tem useState - re-renderiza apenas quando as props mudam
O selectedId do pai é a única fonte de verdade para o estado de destaque
Passar onPress mantém a navegação e os efeitos colaterais na camada do container

Relacionado: ../component-patterns/container-presenter-on-mobile/container-presenter-on-mobile.md - separando hooks de dados de JSX

3. Estado do Servidor vs. Estado do Cliente

Estado do servidor vem de uma API e fica desatualizado. Estado do cliente é a UI que o usuário controla. Misturá-los em um único blob useState causa bugs de re-fetch.

// ❌ Anti-padrão - dados da API em useState com useEffect manual
const [orders, setOrders] = useState<Order[]>([]);
const [loading, setLoading] = useState(true);
 
useEffect(() => {
  fetch("/orders")
    .then((r) => r.json())
    .then(setOrders)
    .finally(() => setLoading(false));
}, []);

// ✅ Estado do servidor no TanStack Query; estado do cliente permanece 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)
  );
 
  // renderizar sorted, isPending, isError, refetch, setSort...
}

orders são de propriedade do servidor - cache, deduplicação e atualização em segundo plano pertencem ao Query
sort é de propriedade do cliente - sem ida e volta à rede quando o usuário alterna
Puxar para atualizar chama refetch() - não um setOrders manual

Relacionado: TanStack Query - políticas de cache para dispositivos móveis | ../architecture-design/adr-state-management-selection/adr-state-management-selection.md - matriz de decisão

4. Estado Global do Cliente (Quando Telas o Compartilham)

Badge do carrinho, modo de tema, conclusão do onboarding - estado que sobrevive à navegação mas não são dados de API se encaixam em um pequeno store global ou Context dividido.

// 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),
}));

// A barra de abas lê a contagem via seletor - não o store inteiro
import { useCartStore } from "@/features/cart/useCartStore";
import { Text, View } from "react-native";
 
export function CartTabIcon() {
  const count = useCartStore((s) => s.count());
  return (
    <View>
      <Text>Carrinho</Text>
      {count > 0 && <Text>{count}</Text>}
    </View>
  );
}

Seletores do Zustand limitam re-renderizações - o ícone da aba atualiza sem re-renderizar a lista do catálogo
Não coloque o catálogo de produtos buscado neste store - isso é estado do servidor
Instale com npx expo install zustand - JS puro, sem módulo nativo

Relacionado: Zustand - slices, devtools e testes

5. Estado da URL com Expo Router

Filtros, abas e paginação que devem ser restaurados em deep links pertencem aos parâmetros de pesquisa da rota - não a um store global.

// 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>Categoria: {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>
  );
}

useLocalSearchParams lê a string de consulta equivalente da rota atual
router.setParams atualiza os parâmetros sem perder a posição da pilha - o botão voltar do sistema operacional restaura o filtro anterior
Links compartilháveis (myapp://catalog?category=gear) funcionam quando scheme é definido em app.config.ts

Relacionado: Rotas Tipadas - parâmetros tipados no SDK 57

6. Redes Intermitentes e Dados Desatualizados

Em dispositivos móveis, assuma que o usuário está offline em um elevador. Mostre os últimos dados válidos com um banner offline sutil - não uma tela em branco.

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 - mostrando resultados salvos</Text>}
      {isFetching && !isPending && <Text>Atualizando…</Text>}
      {/* renderizar dados */}
    </View>
  );
}

staleTime mantém os dados em cache visíveis enquanto uma re-busca em segundo plano é executada
onlineManager informa ao Query quando o dispositivo se reconecta - aciona refetchOnReconnect
gcTime (anteriormente cacheTime) controla quanto tempo o cache não utilizado sobrevive na memória

Relacionado: TanStack Query - focusManager no AppState | ../error-resilience/network-failure-ux/network-failure-ux.md - padrões de UX offline

7. Árvore de Providers Raiz (Mínima)

Conecte provedores de estado do servidor e de sessão uma vez em app/_layout.tsx - evite aninhar provedores por tela.

// 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>
  );
}

QueryClient é criado uma vez por sessão do aplicativo - useState(() => new QueryClient()) evita compartilhamento acidental entre testes e produção no mesmo módulo
SessionProvider expõe a identidade de autenticação - tokens vivem no expo-secure-store, não no cache do Query
Mantenha a árvore plana - aninhamento profundo de provedores retarda o início a frio e complica os testes

Relacionado: Context Without Storms - divida contextos quando os provedores re-renderizam demais

Exemplos Intermediários

8. Dividindo Estado do Servidor e do Cliente em Uma Tela

Uma tela de checkout combina carrinho (cliente), opções de frete (servidor) e método selecionado (cliente). Três baldes, três ferramentas.

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: resumo do carrinho do Zustand, métodos do Query, seleção do useState
}

Itens do carrinho são globais do cliente (Zustand) - o usuário os adicionou em várias telas
Métodos de frete dependem do conteúdo do carrinho - a chave do Query inclui items.length para invalidação
shippingId é UI efêmera nesta tela - useState até o envio, depois mutação

Relacionado: ../architecture-design/clean-architecture-on-mobile/clean-architecture-on-mobile.md - casos de uso vs. hooks

9. Último Dado Válido Conhecido no Início a Frio

Persista o cache do Query no AsyncStorage para que as telas de catálogo renderizem imediatamente após o encerramento do processo - hidrate antes da primeira pintura, quando possível.

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

// app/_layout.tsx (trecho)
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

maxAge limita a idade do cache persistido - combine com staleTime por consulta
Mostre um gate de hidratação ou esqueleto apenas quando não houver dados persistidos - veja o guia de persistência
Logout deve chamar queryClient.clear() e limpar o persister - dados de usuário desatualizados são um bug de segurança

Relacionado: Persistência e Hidratação de Estado - início a frio sem travamentos

10. Checklist de Decisão Antes de Adicionar uma Biblioteca

Execute este checklist quando um colega propuser Redux, Jotai ou outro store.

Checklist de estado (responda antes de npm install):
 
1. É de uma API?           → TanStack Query (ou RTK Query se já usar Redux)
2. É compartilhável em uma URL?    → Parâmetros de pesquisa do Expo Router
3. É um formulário com múltiplos campos?    → React Hook Form + mutação no submit
4. É UI global do cliente?      → Zustand ou Context dividido
5. É efêmero em uma tela? → useState / useReducer
6. É um token secreto?        → expo-secure-store + SessionProvider fino
7. A conformidade precisa de auditoria?  → Redux Toolkit + DevTools
 
Se duas bibliotecas responderem "sim" à mesma pergunta - escolha uma e documente em um ADR.

// Documente o padrão da equipe em um comentário ou link ADR no limite do store
/** @see docs/adr-state-management - servidor: Query, cliente: Zustand, URL: Router */
export const usePreferences = create<PreferencesStore>(/* ... */);

Sete perguntas evitam a instalação de três stores globais sobrepostos
Novas equipes devem ler o ADR antes de introduzir MobX, Jotai ou um segundo wrapper do Query
Reavalie quando os requisitos mudarem - sincronização offline, edição colaborativa ou DevTools obrigatórios

Relacionado: ../architecture-design/adr-state-management-selection/adr-state-management-selection.md - decisões classificadas | Melhores Práticas - resumo da seção

Versões da pilha: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Noções Básicas de Gerenciamento de Estado

Buscar na documentação

Noções Básicas de Gerenciamento de Estado