Conceptos básicos 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

Suposiciones offline-first (contrato de equipo):
 
1. Las lecturas tienen éxito desde caché local incluso cuando isConnected === false
2. Las escrituras se aceptan localmente de inmediato; la confirmación del servidor es asincrónica
3. Los conflictos se resuelven por una estrategia documentada (gana el servidor, LWW o CRDT)
4. Los usuarios siempre saben si los datos son activos, anticuados o pendientes de sincronización
5. El arranque en frío debe renderizar la última versión conocida buena dentro del presupuesto de un fotograma cuando sea posible

// 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}>Actualizando…</Text>;
  }
  const label = isOffline ? "Sin conexión - mostrando datos guardados desde" : "Actualizado";
  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}>Estás sin conexión. Los cambios se sincronizarán cuando te conectes.</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 (fragmento)
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}>
      {/* rutas */}
    </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>Cargando trabajos…</Text>}
      {isError && !data && <Text onPress={() => refetch()}>No se pudo cargar. Toca para reintentar.</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: "Estás sin conexión", action: "Mostrando datos guardados" },
  server: { title: "Servicio temporalmente no disponible", action: "Inténtalo de nuevo" },
  auth: { title: "Sesión expirada", action: "Inicia sesión de nuevo" },
  unknown: { title: "Algo salió mal", action: "Inténtalo de nuevo" },
};

// 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 interfaz de usuario en un compositor de nota
{pendingSync && (
  <Text style={{ color: "#6b7280" }}>Guardado en el dispositivo - se sincronizará cuando esté en línea</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 (fragmento)
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,
    // Saltar refetch de red en modo sin conexión forzada; los datos en caché aún se renderizan vía SWR
    enabled: !forcedOffline,
  });
 
  return (
    <View style={{ flex: 1, padding: 16 }}>
      <OfflineBanner />
      <View style={{ flexDirection: "row", alignItems: "center", marginBottom: 12 }}>
        <Text style={{ flex: 1 }}>Forzar modo sin conexión</Text>
        <Switch value={forcedOffline} onValueChange={setForcedOffline} />
      </View>
      {data && (
        <DataFreshnessLabel
          dataUpdatedAt={dataUpdatedAt}
          isFetching={isFetching}
          isOffline={isOffline}
        />
      )}
      {isPending && !data && <Text>Cargando lista de verificación…</Text>}
      {!data && isOffline && (
        <Text onPress={() => refetch()}>Sin lista de verificación guardada. Conéctate para descargar.</Text>
      )}
      {data?.map((item) => (
        <Text key={item.id}>• {item.label}</Text>
      ))}
    </View>
  );
}

Lista de verificación de ruta de lectura sin conexión:
 
✓ NetInfo + onlineManager cableado en bootstrap
✓ staleTime configurado por sensibilidad de pantalla
✓ Datos en caché mostrados con etiqueta de actualización
✓ Errores sin conexión vs servidor clasificados
✓ Escrituras en cola localmente con claves de idempotencia
✓ Caché de Query persistido para arranque en frío (opcional)
✓ Modo sin conexión forzada para pruebas de campo (opcional)