Noções Básicas de Offline-First

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

Suposições de offline-first (contrato da equipe):
 
1. Leituras são bem-sucedidas do cache local mesmo quando isConnected === false
2. Gravações são aceitas localmente imediatamente; a confirmação do servidor é assíncrona
3. Conflitos são resolvidos por uma estratégia documentada (servidor vence, LWW ou CRDT)
4. Os usuários sempre sabem se os dados estão ao vivo, desatualizados ou pendentes de sincronização
5. A inicialização a frio deve renderizar o último estado conhecido bom dentro do orçamento de um quadro, quando possível

// src/data/offlinePolicy.ts
export const offlinePolicy = {
  maxStaleAgeMs: 24 * 60 * 60 * 1000,
  showOfflineBanner: true,
  allowOptimisticWrites: true,
  conflictStrategy: "server-authoritative" as const,
};

// src/components/DataFreshnessLabel.tsx
import { Text, StyleSheet } from "react-native";
 
type Props = {
  dataUpdatedAt: number;
  isFetching: boolean;
  isOffline: boolean;
};
 
export function DataFreshnessLabel({ dataUpdatedAt, isFetching, isOffline }: Props) {
  if (isFetching) {
    return <Text style={styles.muted}>Atualizando…</Text>;
  }
  const label = isOffline ? "Offline - mostrando dados salvos de" : "Atualizado";
  return (
    <Text style={styles.muted}>
      {label} {new Date(dataUpdatedAt).toLocaleTimeString()}
    </Text>
  );
}
 
const styles = StyleSheet.create({
  muted: { fontSize: 12, color: "#6b7280", marginBottom: 8 },
});

npx expo install @react-native-community/netinfo

// src/hooks/useConnectivity.ts
import { useNetInfo } from "@react-native-community/netinfo";
 
export function useConnectivity() {
  const net = useNetInfo();
 
  const isOffline =
    net.isConnected === false || net.isInternetReachable === false;
 
  const isReachabilityUnknown =
    net.isConnected == null || net.isInternetReachable == null;
 
  return { net, isOffline, isReachabilityUnknown };
}

// src/components/OfflineBanner.tsx
import { StyleSheet, Text, View } from "react-native";
import { useConnectivity } from "@/hooks/useConnectivity";
 
export function OfflineBanner() {
  const { isOffline, isReachabilityUnknown } = useConnectivity();
  if (isReachabilityUnknown || !isOffline) return null;
 
  return (
    <View style={styles.banner} accessibilityRole="alert">
      <Text style={styles.text}>Você está offline. As alterações serão sincronizadas quando conectado.</Text>
    </View>
  );
}
 
const styles = StyleSheet.create({
  banner: { backgroundColor: "#fef3c7", padding: 10 },
  text: { color: "#92400e", textAlign: "center" },
});

// src/lib/setupMobileQuery.ts
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 && state.isInternetReachable !== false;
      setOnline(online);
    })
  );
 
  const onChange = (status: AppStateStatus) => {
    focusManager.setFocused(status === "active");
  };
 
  const sub = AppState.addEventListener("change", onChange);
  return () => sub.remove();
}

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

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

// app/(tabs)/jobs/index.tsx
import { useQuery } from "@tanstack/react-query";
import { FlatList, Text, View } from "react-native";
import { DataFreshnessLabel } from "@/components/DataFreshnessLabel";
import { OfflineBanner } from "@/components/OfflineBanner";
import { useConnectivity } from "@/hooks/useConnectivity";
import { fetchJobs } from "@/api/jobs";
 
export default function JobsScreen() {
  const { isOffline } = useConnectivity();
  const { data, isFetching, isPending, isError, dataUpdatedAt, refetch } = useQuery({
    queryKey: ["jobs"],
    queryFn: fetchJobs,
  });
 
  return (
    <View style={{ flex: 1 }}>
      <OfflineBanner />
      {data && (
        <DataFreshnessLabel
          dataUpdatedAt={dataUpdatedAt}
          isFetching={isFetching}
          isOffline={isOffline}
        />
      )}
      {isPending && !data && <Text>Carregando vagas…</Text>}
      {isError && !data && <Text onPress={() => refetch()}>Não foi possível carregar. Toque para tentar novamente.</Text>}
      <FlatList
        data={data ?? []}
        keyExtractor={(item) => item.id}
        renderItem={({ item }) => <Text>{item.title}</Text>}
      />
    </View>
  );
}

// src/lib/classifyFetchError.ts
import type { NetInfoState } from "@react-native-community/netinfo";
 
export type FailureKind = "offline" | "server" | "auth" | "unknown";
 
export function classifyFailure(error: unknown, net: NetInfoState): FailureKind {
  const offline =
    net.isConnected === false || net.isInternetReachable === false;
  if (offline) return "offline";
 
  if (error instanceof Response) {
    if (error.status === 401 || error.status === 403) return "auth";
    if (error.status >= 500) return "server";
  }
 
  if (error instanceof Error && error.message.includes("Network request failed")) {
    return "offline";
  }
 
  return "unknown";
}

const copy: Record<FailureKind, { title: string; action: string }> = {
  offline: { title: "Você está offline", action: "Mostrando dados salvos" },
  server: { title: "Serviço temporariamente indisponível", action: "Tente novamente" },
  auth: { title: "Sessão expirada", action: "Faça login novamente" },
  unknown: { title: "Algo deu errado", action: "Tente novamente" },
};

// src/data/outbox.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
 
export type OutboxItem = {
  id: string;
  type: "create_note";
  payload: { text: string };
  createdAt: number;
  idempotencyKey: string;
};
 
const OUTBOX_KEY = "sync:outbox:v1";
 
export async function enqueueOutbox(item: OutboxItem) {
  const raw = await AsyncStorage.getItem(OUTBOX_KEY);
  const queue: OutboxItem[] = raw ? JSON.parse(raw) : [];
  queue.push(item);
  await AsyncStorage.setItem(OUTBOX_KEY, JSON.stringify(queue));
}
 
export async function readOutbox(): Promise<OutboxItem[]> {
  const raw = await AsyncStorage.getItem(OUTBOX_KEY);
  return raw ? JSON.parse(raw) : [];
}

// indicador de UI em um compositor de notas
{pendingSync && (
  <Text style={{ color: "#6b7280" }}>Salvo no dispositivo - será sincronizado quando online</Text>
)}

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

// 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",
  throttleTime: 1000,
});

// 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,
    dehydrateOptions: {
      shouldDehydrateQuery: (query) => query.queryKey[0] !== "session",
    },
  }}
>
  {children}
</PersistQueryClientProvider>

// src/stores/offlineModeStore.ts
import { create } from "zustand";
import { persist, createJSONStorage } from "zustand/middleware";
import AsyncStorage from "@react-native-async-storage/async-storage";
 
type OfflineModeStore = {
  forcedOffline: boolean;
  setForcedOffline: (value: boolean) => void;
};
 
export const useOfflineModeStore = create<OfflineModeStore>()(
  persist(
    (set) => ({
      forcedOffline: false,
      setForcedOffline: (forcedOffline) => set({ forcedOffline }),
    }),
    { name: "offline-mode", storage: createJSONStorage(() => AsyncStorage) }
  )
);

// src/hooks/useEffectiveConnectivity.ts
import { useNetInfo } from "@react-native-community/netinfo";
import { useOfflineModeStore } from "@/stores/offlineModeStore";
 
export function useEffectiveConnectivity() {
  const net = useNetInfo();
  const forcedOffline = useOfflineModeStore((s) => s.forcedOffline);
 
  const netOffline =
    net.isConnected === false || net.isInternetReachable === false;
 
  return {
    isOffline: forcedOffline || netOffline,
    forcedOffline,
    netOffline,
  };
}

// src/features/checklist/OfflineChecklistScreen.tsx
import { useQuery } from "@tanstack/react-query";
import { Switch, Text, View } from "react-native";
import { DataFreshnessLabel } from "@/components/DataFreshnessLabel";
import { OfflineBanner } from "@/components/OfflineBanner";
import { useEffectiveConnectivity } from "@/hooks/useEffectiveConnectivity";
import { useOfflineModeStore } from "@/stores/offlineModeStore";
import { fetchChecklist } from "@/api/checklist";
 
export function OfflineChecklistScreen() {
  const { isOffline, forcedOffline } = useEffectiveConnectivity();
  const setForcedOffline = useOfflineModeStore((s) => s.setForcedOffline);
 
  const { data, isFetching, isPending, dataUpdatedAt, refetch } = useQuery({
    queryKey: ["checklist"],
    queryFn: fetchChecklist,
    staleTime: 5 * 60_000,
    // Pula a nova busca de rede no modo offline forçado; dados em cache ainda são renderizados via SWR
    enabled: !forcedOffline,
  });
 
  return (
    <View style={{ flex: 1, padding: 16 }}>
      <OfflineBanner />
      <View style={{ flexDirection: "row", alignItems: "center", marginBottom: 12 }}>
        <Text style={{ flex: 1 }}>Forçar modo offline</Text>
        <Switch value={forcedOffline} onValueChange={setForcedOffline} />
      </View>
      {data && (
        <DataFreshnessLabel
          dataUpdatedAt={dataUpdatedAt}
          isFetching={isFetching}
          isOffline={isOffline}
        />
      )}
      {isPending && !data && <Text>Carregando lista de verificação…</Text>}
      {!data && isOffline && (
        <Text onPress={() => refetch()}>Nenhuma lista de verificação salva. Conecte-se para baixar.</Text>
      )}
      {data?.map((item) => (
        <Text key={item.id}>• {item.label}</Text>
      ))}
    </View>
  );
}

Lista de verificação de leitura offline:
 
✓ NetInfo + onlineManager conectados na inicialização
✓ staleTime configurado por sensibilidade da tela
✓ Dados em cache mostrados com rótulo de frescura
✓ Erros offline vs servidor classificados
✓ Gravações enfileiradas localmente com chaves de idempotência
✓ Cache de consulta persistido para inicialização a frio (opcional)
✓ Modo offline forçado para testes de campo (opcional)