Padrões do AsyncStorage

Q: Como instalo o AsyncStorage no Expo SDK 57?

Sempre use expo install - versões npm manuais podem não corresponder à matriz de módulos nativos do SDK.

Q: Quando devo aumentar a versão do esquema vs renomear a chave?

Aumente schemaVersion quando puder migrar dados no local (adicionar campo, renomear propriedade). Renomeie a chave (:v1 → :v2) quando os dados antigos forem inutilizáveis ou o custo da migração exceder o custo de redownload. Nunca leia código novo contra chaves antigas sem executar migrações na inicialização.

Q: Qual tamanho é muito grande para o AsyncStorage?

Mantenha abaixo de ~500 KB por chave para uma inicialização suave. Analisar JSON de vários megabytes bloqueia a thread JS por centenas de milissegundos. Divida grandes conjuntos de dados em tabelas SQLite ou chaves de cache paginadas.

Q: Como persistir o TanStack Query offline?

Conecte PersistQueryClientProvider com createAsyncStoragePersister. Exclua queries de autenticação e PII da desidratação.

Persistência de chave-valor pequena e versionamento de migração. @react-native-async-storage/async-storage é o armazenamento KV de string padrão para o Expo SDK 57 - ideal para preferências, pequenas caixas de saída, flags de recursos e persistência do TanStack Query. Não é um banco de dados.

Receita

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

npx expo install @react-native-async-storage/async-storage

// src/storage/keys.ts
export const STORAGE_KEYS = {
  meta: "app:storage:meta:v1",
  preferences: "user:preferences:v1",
  outbox: "sync:outbox:v1",
} as const;
 
export type StorageMeta = { schemaVersion: number };

// src/storage/safeJson.ts
export function safeParse<T>(raw: string | null, fallback: T): T {
  if (!raw) return fallback;
  try {
    return JSON.parse(raw) as T;
  } catch {
    return fallback;
  }
}

// src/storage/preferences.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import { STORAGE_KEYS } from "./keys";
import { safeParse } from "./safeJson";
 
export type Preferences = { theme: "light" | "dark"; locale: string };
 
const DEFAULTS: Preferences = { theme: "light", locale: "en" };
 
export async function loadPreferences(): Promise<Preferences> {
  const raw = await AsyncStorage.getItem(STORAGE_KEYS.preferences);
  return safeParse(raw, DEFAULTS);
}
 
export async function savePreferences(prefs: Preferences) {
  await AsyncStorage.setItem(STORAGE_KEYS.preferences, JSON.stringify(prefs));
}

Quando usar isso:

Preferências do usuário, progresso de onboarding, pequenas caixas de saída offline (< poucas centenas de KB)
TanStack Query createAsyncStoragePersister para cache de API do último bom estado conhecido
Padrões de flags de recursos e carimbos de data/hora da última sincronização
Qualquer coisa que caiba em JSON e não precise de consultas SQL

Exemplo de Trabalho

npx expo install @react-native-async-storage/async-storage

// src/storage/keys.ts
export const STORAGE_KEYS = {
  meta: "app:storage:meta:v1",
  preferences: "user:preferences:v1",
  outbox: "sync:outbox:v1",
} as const;
 
export const CURRENT_SCHEMA_VERSION = 2;
 
export type StorageMeta = { schemaVersion: number };

// src/storage/migrations.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import { CURRENT_SCHEMA_VERSION, STORAGE_KEYS, type StorageMeta } from "./keys";
import { safeParse } from "./safeJson";
 
async function readMeta(): Promise<StorageMeta> {
  const raw = await AsyncStorage.getItem(STORAGE_KEYS.meta);
  return safeParse(raw, { schemaVersion: 0 });
}
 
async function writeMeta(meta: StorageMeta) {
  await AsyncStorage.setItem(STORAGE_KEYS.meta, JSON.stringify(meta));
}
 
async function migrateV0ToV1() {
  // v0 tinha a chave "preferences" sem versão
  const legacy = await AsyncStorage.getItem("preferences");
  if (legacy) {
    await AsyncStorage.setItem(STORAGE_KEYS.preferences, legacy);
    await AsyncStorage.removeItem("preferences");
  }
}
 
async function migrateV1ToV2() {
  const raw = await AsyncStorage.getItem(STORAGE_KEYS.preferences);
  const prefs = safeParse(raw, { theme: "light" });
  const next = { ...prefs, locale: prefs.locale ?? "en" };
  await AsyncStorage.setItem(STORAGE_KEYS.preferences, JSON.stringify(next));
}
 
const STEPS: Record<number, () => Promise<void>> = {
  0: migrateV0ToV1,
  1: migrateV1ToV2,
};
 
export async function runStorageMigrations() {
  const meta = await readMeta();
  let version = meta.schemaVersion;
 
  while (version < CURRENT_SCHEMA_VERSION) {
    const step = STEPS[version];
    if (!step) throw new Error(`Missing migration for schema v${version}`);
    await step();
    version += 1;
    await writeMeta({ schemaVersion: version });
  }
}

// app/_layout.tsx (excerpt)
import AsyncStorage from "@react-native-async-storage/async-storage";
import { useEffect, useState } from "react";
import { runStorageMigrations } from "@/storage/migrations";
 
export default function RootLayout() {
  const [ready, setReady] = useState(false);
 
  useEffect(() => {
    runStorageMigrations()
      .then(() => setReady(true))
      .catch(async () => {
        // Recuperação de corrupção: redefinir chaves não críticas e inicializar
        await AsyncStorage.clear();
        setReady(true);
      });
  }, []);
 
  if (!ready) return null;
  return <Stack />;
}

// src/storage/outbox.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import { STORAGE_KEYS } from "./keys";
import { safeParse } from "./safeJson";
 
export type OutboxItem = {
  id: string;
  type: string;
  payload: unknown;
  idempotencyKey: string;
  createdAt: number;
};
 
export async function readOutbox(): Promise<OutboxItem[]> {
  const raw = await AsyncStorage.getItem(STORAGE_KEYS.outbox);
  return safeParse(raw, []);
}
 
export async function appendOutbox(item: OutboxItem) {
  const queue = await readOutbox();
  queue.push(item);
  await AsyncStorage.setItem(STORAGE_KEYS.outbox, JSON.stringify(queue));
}
 
export async function writeOutbox(queue: OutboxItem[]) {
  await AsyncStorage.setItem(STORAGE_KEYS.outbox, JSON.stringify(queue));
}

# Opcional: persistência do TanStack Query
npx expo install @tanstack/react-query-persist-client @tanstack/query-async-storage-persister

Mergulho Profundo

Namespace de chaves

Trate cada domínio como um documento isolado com um sufixo de versão na chave:

Chave	Conteúdo	Orientação de tamanho máximo
`user:preferences:v1`	Tema, local	< 4 KB
`sync:outbox:v1`	Mutações pendentes	< 500 KB - descarregar frequentemente
`REACT_QUERY_OFFLINE_CACHE`	Cache de Query desidratado	Monitorar crescimento; excluir segredos
`app:storage:meta:v1`	`{ schemaVersion }`	Pequeno

Aumente o sufixo :v1 quando a forma mudar irreversivelmente - migrações lidam com upgrades no local; renomear chaves lida com reescritas que quebram compatibilidade.

Migrações passo a passo

Sequência de inicialização:
 
1. Ler app:storage:meta:v1 → schemaVersion (padrão 0)
2. Enquanto version < CURRENT_SCHEMA_VERSION:
     executar STEPS[version]()
     version++
     persistir meta
3. App renderiza - nenhuma tela lê chaves não migradas

Migrações executam uma vez por etapa de versão - etapas idempotentes são mais seguras para travamentos no meio da migração
Registrar falhas de migração no seu relatador de falhas - clear() silencioso perde dados do usuário
Para transformações grandes, escreva em uma nova chave e depois troque - evita JSON meio escrito em caso de encerramento forçado

Recuperação de corrupção

export async function loadWithRecovery<T>(
  key: string,
  fallback: T,
  onCorrupt?: () => void
): Promise<T> {
  try {
    const raw = await AsyncStorage.getItem(key);
    return safeParse(raw, fallback);
  } catch {
    onCorrupt?.();
    await AsyncStorage.removeItem(key);
    return fallback;
  }
}

Corrupção de preferências → redefinir para os padrões e mostrar um toast único
Corrupção da caixa de saída → colocar em quarentena em sync:outbox:corrupt:<timestamp> para exportação de suporte antes de limpar
Nunca chame AsyncStorage.clear() apenas em erros de autenticação - escopo de limpezas para namespaces afetados

Agrupamento e multi-set

import AsyncStorage from "@react-native-async-storage/async-storage";
 
export async function saveDraftBundle(draft: object, updatedAt: number) {
  await AsyncStorage.multiSet([
    ["draft:composer:v1", JSON.stringify(draft)],
    ["draft:composer:meta:v1", JSON.stringify({ updatedAt })],
  ]);
}

multiSet reduz as idas e vindas da ponte em comparação com chamadas setItem sequenciais - ainda é assíncrono, não síncrono como MMKV.

Armadilhas

Armazenar listas grandes em um único array JSON - Analisar 5 MB na thread JS bloqueia a UI. Correção: Mover dados relacionais para expo-sqlite; manter AsyncStorage para metadados e ponteiros da caixa de saída.
Sem versão de esquema - Lançar uma nova forma sem migração trava as suposições do JSON.parse. Correção: Sempre manter app:storage:meta:v1 e migrações passo a passo.
Armazenar segredos no AsyncStorage - Não é criptografado. Correção: Tokens em expo-secure-store; apenas preferências não sensíveis no AsyncStorage.
Corrida em escritas concorrentes - Duas telas adicionando à mesma caixa de saída podem perder itens. Correção: Ler-modificar-escrever em uma única função; serializar descarregamentos com um mutex ou serviço de fila.
Assumir que a persistência é síncrona - await getItem em cada renderização causa lentidão. Correção: Carregar uma vez na inicialização ou hidratar Zustand/Query; usar MMKV para caminhos críticos síncronos.
Crescimento ilimitado do persister de Query - Desidratar todas as queries enche o disco. Correção: Filtro shouldDehydrateQuery + maxAge; ver ../state-management/tanstack-query/tanstack-query.md.
Esquecer a limpeza de logout - O cache do usuário anterior vaza para o próximo login. Correção: multiRemove em chaves de sessão + queryClient.clear() ao sair.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`@react-native-async-storage/async-storage`	JSON pequeno, preferências, persister de Query	Você precisa de SQL, pesquisa de texto completo ou junções síncronas
`expo-sqlite/kv-store`	Já está usando SQLite; quer API compatível com AsyncStorage + leituras síncronas	Você só precisa de algumas chaves e ainda não tem um banco de dados
`react-native-mmkv`	Flags de caminho crítico, cache adjacente à sessão, leituras frequentes	Expo Go sem build de desenvolvimento; blobs de vários MB
`expo-secure-store`	Tokens, segredos de atualização	Cargas úteis grandes (> ~2 KB por chave em algumas plataformas)
Apenas cache do TanStack Query	Estado puro do servidor sem escritas apenas locais	Linhas criadas offline que nunca chegam ao servidor

FAQs

Como instalo o AsyncStorage no Expo SDK 57?

npx expo install @react-native-async-storage/async-storage

Sempre use expo install - versões npm manuais podem não corresponder à matriz de módulos nativos do SDK.

Quando devo aumentar a versão do esquema vs renomear a chave?

Aumente schemaVersion quando puder migrar dados no local (adicionar campo, renomear propriedade).
Renomeie a chave (:v1 → :v2) quando os dados antigos forem inutilizáveis ou o custo da migração exceder o custo de redownload.
Nunca leia código novo contra chaves antigas sem executar migrações na inicialização.

Qual tamanho é muito grande para o AsyncStorage?

Mantenha abaixo de ~500 KB por chave para uma inicialização suave. Analisar JSON de vários megabytes bloqueia a thread JS por centenas de milissegundos. Divida grandes conjuntos de dados em tabelas SQLite ou chaves de cache paginadas.

O AsyncStorage pode substituir um banco de dados de servidor?

Não. É uma camada de conveniência local. Trate o conteúdo como cache de melhor esforço com TTL, versão e reconciliação com o servidor - veja Estratégias de Sincronização.

Como persistir o TanStack Query offline?

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

Conecte PersistQueryClientProvider com createAsyncStoragePersister. Exclua queries de autenticação e PII da desidratação.

E se a migração lançar um erro durante a inicialização?

Tente novamente uma vez - erros de E/S transitórios ocorrem com pouco armazenamento.
Na segunda falha, coloque em quarentena as chaves corrompidas, redefina namespaces não críticos e registre na telemetria.
Ofereça exportação de suporte para quarentena da caixa de saída antes de apagar em aplicativos em campo.

Devo usar o persist do Zustand com AsyncStorage?

Sim, para estado da UI do cliente (filtros, rascunhos de formulários). Use createJSONStorage(() => AsyncStorage) e a mesma disciplina de migração/versão. Dados da API do servidor ainda pertencem ao TanStack Query.

O AsyncStorage é criptografado?

Não por padrão. Assuma que dispositivos com root/jailbreak podem lê-lo. Segredos → SecureStore; PII sensível → minimize a retenção ou criptografe em repouso com uma chave derivada do servidor.

Relacionados

Noções Básicas de Offline-First - UX de conectividade e padrões SWR
expo-sqlite - dados relacionais e consultas tipadas
MMKV e KV de Alto Desempenho - quando AsyncStorage é muito lento
../state-management/tanstack-query/tanstack-query.md - persistência de cache e ciclo de vida móvel
UI Otimista - repetição da caixa de saída após mutações falhas
Melhores Práticas da Camada de Dados - resumo da seção

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 receita de referência rápida - pronto para copiar e colar.

npx expo install @react-native-async-storage/async-storage

// src/storage/keys.ts
export const STORAGE_KEYS = {
  meta: "app:storage:meta:v1",
  preferences: "user:preferences:v1",
  outbox: "sync:outbox:v1",
} as const;
 
export type StorageMeta = { schemaVersion: number };

// src/storage/safeJson.ts
export function safeParse<T>(raw: string | null, fallback: T): T {
  if (!raw) return fallback;
  try {
    return JSON.parse(raw) as T;
  } catch {
    return fallback;
  }
}

// src/storage/preferences.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import { STORAGE_KEYS } from "./keys";
import { safeParse } from "./safeJson";
 
export type Preferences = { theme: "light" | "dark"; locale: string };
 
const DEFAULTS: Preferences = { theme: "light", locale: "en" };
 
export async function loadPreferences(): Promise<Preferences> {
  const raw = await AsyncStorage.getItem(STORAGE_KEYS.preferences);
  return safeParse(raw, DEFAULTS);
}
 
export async function savePreferences(prefs: Preferences) {
  await AsyncStorage.setItem(STORAGE_KEYS.preferences, JSON.stringify(prefs));
}

Quando usar isso:

Preferências do usuário, progresso de onboarding, pequenas caixas de saída offline (< poucas centenas de KB)
TanStack Query createAsyncStoragePersister para cache de API do último bom estado conhecido
Padrões de flags de recursos e carimbos de data/hora da última sincronização
Qualquer coisa que caiba em JSON e não precise de consultas SQL

Exemplo de Trabalho

npx expo install @react-native-async-storage/async-storage

// src/storage/keys.ts
export const STORAGE_KEYS = {
  meta: "app:storage:meta:v1",
  preferences: "user:preferences:v1",
  outbox: "sync:outbox:v1",
} as const;
 
export const CURRENT_SCHEMA_VERSION = 2;
 
export type StorageMeta = { schemaVersion: number };

// src/storage/migrations.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import { CURRENT_SCHEMA_VERSION, STORAGE_KEYS, type StorageMeta } from "./keys";
import { safeParse } from "./safeJson";
 
async function readMeta(): Promise<StorageMeta> {
  const raw = await AsyncStorage.getItem(STORAGE_KEYS.meta);
  return safeParse(raw, { schemaVersion: 0 });
}
 
async function writeMeta(meta: StorageMeta) {
  await AsyncStorage.setItem(STORAGE_KEYS.meta, JSON.stringify(meta));
}
 
async function migrateV0ToV1() {
  // v0 tinha a chave "preferences" sem versão
  const legacy = await AsyncStorage.getItem("preferences");
  if (legacy) {
    await AsyncStorage.setItem(STORAGE_KEYS.preferences, legacy);
    await AsyncStorage.removeItem("preferences");
  }
}
 
async function migrateV1ToV2() {
  const raw = await AsyncStorage.getItem(STORAGE_KEYS.preferences);
  const prefs = safeParse(raw, { theme: "light" });
  const next = { ...prefs, locale: prefs.locale ?? "en" };
  await AsyncStorage.setItem(STORAGE_KEYS.preferences, JSON.stringify(next));
}
 
const STEPS: Record<number, () => Promise<void>> = {
  0: migrateV0ToV1,
  1: migrateV1ToV2,
};
 
export async function runStorageMigrations() {
  const meta = await readMeta();
  let version = meta.schemaVersion;
 
  while (version < CURRENT_SCHEMA_VERSION) {
    const step = STEPS[version];
    if (!step) throw new Error(`Missing migration for schema v${version}`);
    await step();
    version += 1;
    await writeMeta({ schemaVersion: version });
  }
}

// app/_layout.tsx (excerpt)
import AsyncStorage from "@react-native-async-storage/async-storage";
import { useEffect, useState } from "react";
import { runStorageMigrations } from "@/storage/migrations";
 
export default function RootLayout() {
  const [ready, setReady] = useState(false);
 
  useEffect(() => {
    runStorageMigrations()
      .then(() => setReady(true))
      .catch(async () => {
        // Recuperação de corrupção: redefinir chaves não críticas e inicializar
        await AsyncStorage.clear();
        setReady(true);
      });
  }, []);
 
  if (!ready) return null;
  return <Stack />;
}

// src/storage/outbox.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import { STORAGE_KEYS } from "./keys";
import { safeParse } from "./safeJson";
 
export type OutboxItem = {
  id: string;
  type: string;
  payload: unknown;
  idempotencyKey: string;
  createdAt: number;
};
 
export async function readOutbox(): Promise<OutboxItem[]> {
  const raw = await AsyncStorage.getItem(STORAGE_KEYS.outbox);
  return safeParse(raw, []);
}
 
export async function appendOutbox(item: OutboxItem) {
  const queue = await readOutbox();
  queue.push(item);
  await AsyncStorage.setItem(STORAGE_KEYS.outbox, JSON.stringify(queue));
}
 
export async function writeOutbox(queue: OutboxItem[]) {
  await AsyncStorage.setItem(STORAGE_KEYS.outbox, JSON.stringify(queue));
}

# Opcional: persistência do TanStack Query
npx expo install @tanstack/react-query-persist-client @tanstack/query-async-storage-persister

Mergulho Profundo

Namespace de chaves

Trate cada domínio como um documento isolado com um sufixo de versão na chave:

Chave	Conteúdo	Orientação de tamanho máximo
`user:preferences:v1`	Tema, local	< 4 KB
`sync:outbox:v1`	Mutações pendentes	< 500 KB - descarregar frequentemente
`REACT_QUERY_OFFLINE_CACHE`	Cache de Query desidratado	Monitorar crescimento; excluir segredos
`app:storage:meta:v1`	`{ schemaVersion }`	Pequeno

Aumente o sufixo :v1 quando a forma mudar irreversivelmente - migrações lidam com upgrades no local; renomear chaves lida com reescritas que quebram compatibilidade.

Migrações passo a passo

Sequência de inicialização:
 
1. Ler app:storage:meta:v1 → schemaVersion (padrão 0)
2. Enquanto version < CURRENT_SCHEMA_VERSION:
     executar STEPS[version]()
     version++
     persistir meta
3. App renderiza - nenhuma tela lê chaves não migradas

Migrações executam uma vez por etapa de versão - etapas idempotentes são mais seguras para travamentos no meio da migração
Registrar falhas de migração no seu relatador de falhas - clear() silencioso perde dados do usuário
Para transformações grandes, escreva em uma nova chave e depois troque - evita JSON meio escrito em caso de encerramento forçado

Recuperação de corrupção

export async function loadWithRecovery<T>(
  key: string,
  fallback: T,
  onCorrupt?: () => void
): Promise<T> {
  try {
    const raw = await AsyncStorage.getItem(key);
    return safeParse(raw, fallback);
  } catch {
    onCorrupt?.();
    await AsyncStorage.removeItem(key);
    return fallback;
  }
}

Corrupção de preferências → redefinir para os padrões e mostrar um toast único
Corrupção da caixa de saída → colocar em quarentena em sync:outbox:corrupt:<timestamp> para exportação de suporte antes de limpar
Nunca chame AsyncStorage.clear() apenas em erros de autenticação - escopo de limpezas para namespaces afetados

Agrupamento e multi-set

import AsyncStorage from "@react-native-async-storage/async-storage";
 
export async function saveDraftBundle(draft: object, updatedAt: number) {
  await AsyncStorage.multiSet([
    ["draft:composer:v1", JSON.stringify(draft)],
    ["draft:composer:meta:v1", JSON.stringify({ updatedAt })],
  ]);
}

multiSet reduz as idas e vindas da ponte em comparação com chamadas setItem sequenciais - ainda é assíncrono, não síncrono como MMKV.

Armadilhas

Armazenar listas grandes em um único array JSON - Analisar 5 MB na thread JS bloqueia a UI. Correção: Mover dados relacionais para expo-sqlite; manter AsyncStorage para metadados e ponteiros da caixa de saída.
Sem versão de esquema - Lançar uma nova forma sem migração trava as suposições do JSON.parse. Correção: Sempre manter app:storage:meta:v1 e migrações passo a passo.
Armazenar segredos no AsyncStorage - Não é criptografado. Correção: Tokens em expo-secure-store; apenas preferências não sensíveis no AsyncStorage.
Corrida em escritas concorrentes - Duas telas adicionando à mesma caixa de saída podem perder itens. Correção: Ler-modificar-escrever em uma única função; serializar descarregamentos com um mutex ou serviço de fila.
Assumir que a persistência é síncrona - await getItem em cada renderização causa lentidão. Correção: Carregar uma vez na inicialização ou hidratar Zustand/Query; usar MMKV para caminhos críticos síncronos.
Crescimento ilimitado do persister de Query - Desidratar todas as queries enche o disco. Correção: Filtro shouldDehydrateQuery + maxAge; ver ../state-management/tanstack-query/tanstack-query.md.
Esquecer a limpeza de logout - O cache do usuário anterior vaza para o próximo login. Correção: multiRemove em chaves de sessão + queryClient.clear() ao sair.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`@react-native-async-storage/async-storage`	JSON pequeno, preferências, persister de Query	Você precisa de SQL, pesquisa de texto completo ou junções síncronas
`expo-sqlite/kv-store`	Já está usando SQLite; quer API compatível com AsyncStorage + leituras síncronas	Você só precisa de algumas chaves e ainda não tem um banco de dados
`react-native-mmkv`	Flags de caminho crítico, cache adjacente à sessão, leituras frequentes	Expo Go sem build de desenvolvimento; blobs de vários MB
`expo-secure-store`	Tokens, segredos de atualização	Cargas úteis grandes (> ~2 KB por chave em algumas plataformas)
Apenas cache do TanStack Query	Estado puro do servidor sem escritas apenas locais	Linhas criadas offline que nunca chegam ao servidor

FAQs

Como instalo o AsyncStorage no Expo SDK 57?

npx expo install @react-native-async-storage/async-storage

Sempre use expo install - versões npm manuais podem não corresponder à matriz de módulos nativos do SDK.

Quando devo aumentar a versão do esquema vs renomear a chave?

Aumente schemaVersion quando puder migrar dados no local (adicionar campo, renomear propriedade).
Renomeie a chave (:v1 → :v2) quando os dados antigos forem inutilizáveis ou o custo da migração exceder o custo de redownload.
Nunca leia código novo contra chaves antigas sem executar migrações na inicialização.

Qual tamanho é muito grande para o AsyncStorage?

O AsyncStorage pode substituir um banco de dados de servidor?

Não. É uma camada de conveniência local. Trate o conteúdo como cache de melhor esforço com TTL, versão e reconciliação com o servidor - veja Estratégias de Sincronização.

Como persistir o TanStack Query offline?

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

Conecte PersistQueryClientProvider com createAsyncStoragePersister. Exclua queries de autenticação e PII da desidratação.

E se a migração lançar um erro durante a inicialização?

Tente novamente uma vez - erros de E/S transitórios ocorrem com pouco armazenamento.
Na segunda falha, coloque em quarentena as chaves corrompidas, redefina namespaces não críticos e registre na telemetria.
Ofereça exportação de suporte para quarentena da caixa de saída antes de apagar em aplicativos em campo.

Devo usar o persist do Zustand com AsyncStorage?

O AsyncStorage é criptografado?

Relacionados

Noções Básicas de Offline-First - UX de conectividade e padrões SWR
expo-sqlite - dados relacionais e consultas tipadas
MMKV e KV de Alto Desempenho - quando AsyncStorage é muito lento
../state-management/tanstack-query/tanstack-query.md - persistência de cache e ciclo de vida móvel
UI Otimista - repetição da caixa de saída após mutações falhas
Melhores Práticas da Camada de Dados - resumo da seção

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).

Padrões do AsyncStorage

Buscar na documentação

Padrões do AsyncStorage