@tanstack/react-query

Q: Query precisa de um rebuild nativo?

Não - @tanstack/react-query é apenas JS. @react-native-community/netinfo é instalado via npx expo install e pode exigir um refresh do dev client em alguns SDKs.

Q: Como testar componentes que usam useQuery?

Envolva com QueryClientProvider usando um cliente de teste com retry: false e gcTime: Infinity. Veja Noções Básicas de Teste Mobile.

Padrões de estado do servidor para aplicativos Expo. TanStack Query é a camada padrão de estado do servidor - substitui buscas useEffect feitas manualmente e mantém os dados da API fora do Zustand. Para políticas de cache, persistência offline e mutações otimistas, consulte o guia completo em TanStack Query.

Receita

Cartão de referência rápida - pronto para copiar e colar.

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

// src/lib/queryClient.ts
import { QueryClient } from "@tanstack/react-query";
 
export function createQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 30_000,
        gcTime: 5 * 60_000,
        retry: 2,
        refetchOnReconnect: true,
        refetchOnWindowFocus: true, // conectado via focusManager abaixo
      },
      mutations: {
        retry: 1,
      },
    },
  });
}

// src/lib/setupMobileQuery.ts - chame uma vez no bootstrap
import NetInfo from "@react-native-community/netinfo";
import { AppState, type AppStateStatus } from "react-native";
import { focusManager, onlineManager } from "@tanstack/react-query";
 
export function setupMobileQuery() {
  onlineManager.setEventListener((setOnline) =>
    NetInfo.addEventListener((state) => {
      const online =
        state.isConnected !== false && state.isInternetReachable !== false;
      setOnline(online);
    })
  );
 
  const onAppStateChange = (status: AppStateStatus) => {
    focusManager.setFocused(status === "active");
  };
 
  const sub = AppState.addEventListener("change", onAppStateChange);
  return () => sub.remove();
}

// app/_layout.tsx
import { QueryClientProvider } from "@tanstack/react-query";
import { Stack } from "expo-router";
import { useEffect, useState } from "react";
import { createQueryClient } from "@/lib/queryClient";
import { setupMobileQuery } from "@/lib/setupMobileQuery";
 
export default function RootLayout() {
  const [client] = useState(createQueryClient);
 
  useEffect(() => setupMobileQuery(), []);
 
  return (
    <QueryClientProvider client={client}>
      <Stack />
    </QueryClientProvider>
  );
}

Quando usar isso:

Mesmos dados da API em várias telas - cache por queryKey.
Pull-to-refresh, refetch em segundo plano ou stale-while-revalidate em LTE instável.
Mutations devem invalidar queries relacionadas após createOrder, updateProfile, etc.
Você precisa de dados da API fora do Redux, Zustand e do "espaguete" de useEffect.

Exemplo de Trabalho

// api/orders.ts
export type Order = { id: string; status: string; totalCents: number };
 
export async function fetchOrders(signal?: AbortSignal): Promise<Order[]> {
  const res = await fetch("https://api.example.com/orders", { signal });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

// screens/OrdersScreen.tsx
import { useQuery } from "@tanstack/react-query";
import { useCallback, useState } from "react";
import { FlatList, RefreshControl, Text, View } from "react-native";
import { fetchOrders } from "@/api/orders";
 
export function OrdersScreen() {
  const [refreshing, setRefreshing] = useState(false);
 
  const { data: orders = [], isPending, isError, error, refetch, isFetching } = useQuery({
    queryKey: ["orders"],
    queryFn: ({ signal }) => fetchOrders(signal),
    staleTime: 60_000,
  });
 
  const onRefresh = useCallback(async () => {
    setRefreshing(true);
    await refetch();
    setRefreshing(false);
  }, [refetch]);
 
  if (isPending) return <Text>Carregando…</Text>;
  if (isError) return <Text>Erro: {(error as Error).message}</Text>;
 
  return (
    <View style={{ flex: 1 }}>
      {isFetching && !refreshing && <Text>Atualizando…</Text>}
      <FlatList
        data={orders}
        keyExtractor={(o) => o.id}
        refreshControl={<RefreshControl refreshing={refreshing} onRefresh={onRefresh} />}
        renderItem={({ item }) => (
          <Text>
            {item.id} - {item.status} - ${(item.totalCents / 100).toFixed(2)}
          </Text>
        )}
      />
    </View>
  );
}

O que isso demonstra:

staleTime: 60_000 - navegar para fora e voltar dentro de um minuto não refaz a busca.
signal em queryFn - Query cancela a busca em andamento quando a tela é desmontada.
focusManager + AppState - retornar do background refaz automaticamente queries obsoletas.
onlineManager + NetInfo - pausa retentativas offline; refetchOnReconnect é acionado ao retornar do LTE.
Sem Zustand - linhas de pedido vivem no cache da Query, não em um store global.

Mergulho Profundo

Referência de Opções Padrão

Opção	Padrão na receita	Orientação móvel
`staleTime`	`30_000`	Catálogos: 1–5 min; saldos: 0–30s
`gcTime`	`5 * 60_000`	Retenção de cache inativo após desmontar
`retry`	`2`	Pare mais cedo no celular para economizar bateria
`refetchOnReconnect`	`true`	Emparelhe com `onlineManager`
`refetchOnWindowFocus`	`true`	Requer `focusManager` no RN

Convenções de Chave de Query

["products"][("products", { category: "shoes" })][("order", orderId)][
  // Invalida todas as queries de produtos após uma mutation
  queryClient.invalidateQueries({ queryKey: ["products"] })
];

Inclua parâmetros serializáveis estáveis - não funções, instâncias de classe ou valores não-JSON.

Persistência (Opcional)

Para shells "read-mostly" offline, adicione persistência - padrões completos em TanStack Query:

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

Armadilhas

Pular setupMobileQuery - Queries nunca refazem ao focar; retentativas continuam offline. Correção: Conecte focusManager e onlineManager no bootstrap.
Armazenar respostas da API no Zustand - Invalidação manual de cache em cada mutation. Correção: Query possui dados do servidor; Zustand possui apenas flags de UI.
Novo QueryClient por tela - Cache não compartilha entre rotas. Correção: Um cliente em _layout.tsx via useState(createQueryClient).
staleTime: 0 em todos os lugares - Tempestade de refetch em cada foco de aba drena a bateria. Correção: Ajuste por query - configurações estáveis podem usar minutos.
signal ausente no fetch - Requisições em andamento completam após a desmontagem, causando avisos de setState. Correção: Encaminhe signal de queryFn para fetch.

Alternativas

Alternativa	Use Quando	Não Use Quando
TanStack Query	Cache do servidor, mutations, deduplicação	Alternâncias efêmeras apenas de UI
Zustand	Ícone do carrinho, filtros, flags de onboarding	Catálogo de produtos da API
RTK Query	Equipe já usa Redux Toolkit	Greenfield apenas com leituras REST
SWR	Web-first monorepo compartilhando hooks	Wiring de foco/online do RN é manual
`useEffect` + `fetch` Brutos	Apenas protótipo	Qualquer tela reutilizada duas vezes

FAQs

Onde está o guia completo do TanStack Query?

TanStack Query em Gerenciamento de Estado - persistência offline, mutações otimistas, queries infinitas e persistidores SQLite.

Query precisa de um rebuild nativo?

Não - @tanstack/react-query é apenas JS. @react-native-community/netinfo é instalado via npx expo install e pode exigir um refresh do dev client em alguns SDKs.

Qual staleTime feeds devem usar?

30–60 segundos é um padrão sensato. Aumente para dados que mudam raramente; diminua para dashboards ao vivo.

Como testar componentes que usam useQuery?

Envolva com QueryClientProvider usando um cliente de teste com retry: false e gcTime: Infinity. Veja Noções Básicas de Teste Mobile.

Query pode substituir Zustand?

Não para estado de UI do cliente. Sim para entidades buscadas do servidor. Use ambos - veja zustand.

Relacionados

TanStack Query - cookbook completo de estado do servidor
TanStack Query no Mobile - detalhes do gerenciador de foco/online
zustand - limite de estado do cliente
UX de Falha de Rede - banners offline e filas de mutation
Scroll Infinito e Paginação - useInfiniteQuery
Noções Básicas de Bibliotecas Essenciais - escolha e fixe dependências

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

Receita

Cartão de referência rápida - pronto para copiar e colar.

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

// src/lib/queryClient.ts
import { QueryClient } from "@tanstack/react-query";
 
export function createQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 30_000,
        gcTime: 5 * 60_000,
        retry: 2,
        refetchOnReconnect: true,
        refetchOnWindowFocus: true, // conectado via focusManager abaixo
      },
      mutations: {
        retry: 1,
      },
    },
  });
}

// src/lib/setupMobileQuery.ts - chame uma vez no bootstrap
import NetInfo from "@react-native-community/netinfo";
import { AppState, type AppStateStatus } from "react-native";
import { focusManager, onlineManager } from "@tanstack/react-query";
 
export function setupMobileQuery() {
  onlineManager.setEventListener((setOnline) =>
    NetInfo.addEventListener((state) => {
      const online =
        state.isConnected !== false && state.isInternetReachable !== false;
      setOnline(online);
    })
  );
 
  const onAppStateChange = (status: AppStateStatus) => {
    focusManager.setFocused(status === "active");
  };
 
  const sub = AppState.addEventListener("change", onAppStateChange);
  return () => sub.remove();
}

// app/_layout.tsx
import { QueryClientProvider } from "@tanstack/react-query";
import { Stack } from "expo-router";
import { useEffect, useState } from "react";
import { createQueryClient } from "@/lib/queryClient";
import { setupMobileQuery } from "@/lib/setupMobileQuery";
 
export default function RootLayout() {
  const [client] = useState(createQueryClient);
 
  useEffect(() => setupMobileQuery(), []);
 
  return (
    <QueryClientProvider client={client}>
      <Stack />
    </QueryClientProvider>
  );
}

Quando usar isso:

Mesmos dados da API em várias telas - cache por queryKey.
Pull-to-refresh, refetch em segundo plano ou stale-while-revalidate em LTE instável.
Mutations devem invalidar queries relacionadas após createOrder, updateProfile, etc.
Você precisa de dados da API fora do Redux, Zustand e do "espaguete" de useEffect.

Exemplo de Trabalho

// api/orders.ts
export type Order = { id: string; status: string; totalCents: number };
 
export async function fetchOrders(signal?: AbortSignal): Promise<Order[]> {
  const res = await fetch("https://api.example.com/orders", { signal });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

// screens/OrdersScreen.tsx
import { useQuery } from "@tanstack/react-query";
import { useCallback, useState } from "react";
import { FlatList, RefreshControl, Text, View } from "react-native";
import { fetchOrders } from "@/api/orders";
 
export function OrdersScreen() {
  const [refreshing, setRefreshing] = useState(false);
 
  const { data: orders = [], isPending, isError, error, refetch, isFetching } = useQuery({
    queryKey: ["orders"],
    queryFn: ({ signal }) => fetchOrders(signal),
    staleTime: 60_000,
  });
 
  const onRefresh = useCallback(async () => {
    setRefreshing(true);
    await refetch();
    setRefreshing(false);
  }, [refetch]);
 
  if (isPending) return <Text>Carregando…</Text>;
  if (isError) return <Text>Erro: {(error as Error).message}</Text>;
 
  return (
    <View style={{ flex: 1 }}>
      {isFetching && !refreshing && <Text>Atualizando…</Text>}
      <FlatList
        data={orders}
        keyExtractor={(o) => o.id}
        refreshControl={<RefreshControl refreshing={refreshing} onRefresh={onRefresh} />}
        renderItem={({ item }) => (
          <Text>
            {item.id} - {item.status} - ${(item.totalCents / 100).toFixed(2)}
          </Text>
        )}
      />
    </View>
  );
}

O que isso demonstra:

staleTime: 60_000 - navegar para fora e voltar dentro de um minuto não refaz a busca.
signal em queryFn - Query cancela a busca em andamento quando a tela é desmontada.
focusManager + AppState - retornar do background refaz automaticamente queries obsoletas.
onlineManager + NetInfo - pausa retentativas offline; refetchOnReconnect é acionado ao retornar do LTE.
Sem Zustand - linhas de pedido vivem no cache da Query, não em um store global.

Mergulho Profundo

Referência de Opções Padrão

Opção	Padrão na receita	Orientação móvel
`staleTime`	`30_000`	Catálogos: 1–5 min; saldos: 0–30s
`gcTime`	`5 * 60_000`	Retenção de cache inativo após desmontar
`retry`	`2`	Pare mais cedo no celular para economizar bateria
`refetchOnReconnect`	`true`	Emparelhe com `onlineManager`
`refetchOnWindowFocus`	`true`	Requer `focusManager` no RN

Convenções de Chave de Query

["products"][("products", { category: "shoes" })][("order", orderId)][
  // Invalida todas as queries de produtos após uma mutation
  queryClient.invalidateQueries({ queryKey: ["products"] })
];

Inclua parâmetros serializáveis estáveis - não funções, instâncias de classe ou valores não-JSON.

Persistência (Opcional)

Para shells "read-mostly" offline, adicione persistência - padrões completos em TanStack Query:

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

Armadilhas

Pular setupMobileQuery - Queries nunca refazem ao focar; retentativas continuam offline. Correção: Conecte focusManager e onlineManager no bootstrap.
Armazenar respostas da API no Zustand - Invalidação manual de cache em cada mutation. Correção: Query possui dados do servidor; Zustand possui apenas flags de UI.
Novo QueryClient por tela - Cache não compartilha entre rotas. Correção: Um cliente em _layout.tsx via useState(createQueryClient).
staleTime: 0 em todos os lugares - Tempestade de refetch em cada foco de aba drena a bateria. Correção: Ajuste por query - configurações estáveis podem usar minutos.
signal ausente no fetch - Requisições em andamento completam após a desmontagem, causando avisos de setState. Correção: Encaminhe signal de queryFn para fetch.

Alternativas

Alternativa	Use Quando	Não Use Quando
TanStack Query	Cache do servidor, mutations, deduplicação	Alternâncias efêmeras apenas de UI
Zustand	Ícone do carrinho, filtros, flags de onboarding	Catálogo de produtos da API
RTK Query	Equipe já usa Redux Toolkit	Greenfield apenas com leituras REST
SWR	Web-first monorepo compartilhando hooks	Wiring de foco/online do RN é manual
`useEffect` + `fetch` Brutos	Apenas protótipo	Qualquer tela reutilizada duas vezes

FAQs

Onde está o guia completo do TanStack Query?

TanStack Query em Gerenciamento de Estado - persistência offline, mutações otimistas, queries infinitas e persistidores SQLite.

Query precisa de um rebuild nativo?

Não - @tanstack/react-query é apenas JS. @react-native-community/netinfo é instalado via npx expo install e pode exigir um refresh do dev client em alguns SDKs.

Qual staleTime feeds devem usar?

30–60 segundos é um padrão sensato. Aumente para dados que mudam raramente; diminua para dashboards ao vivo.

Como testar componentes que usam useQuery?

Envolva com QueryClientProvider usando um cliente de teste com retry: false e gcTime: Infinity. Veja Noções Básicas de Teste Mobile.

Query pode substituir Zustand?

Não para estado de UI do cliente. Sim para entidades buscadas do servidor. Use ambos - veja zustand.

Relacionados

TanStack Query - cookbook completo de estado do servidor
TanStack Query no Mobile - detalhes do gerenciador de foco/online
zustand - limite de estado do cliente
UX de Falha de Rede - banners offline e filas de mutation
Scroll Infinito e Paginação - useInfiniteQuery
Noções Básicas de Bibliotecas Essenciais - escolha e fixe dependências

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

@tanstack/react-query

Buscar na documentação

@tanstack/react-query