Capítulo 261 de 456

useOffline

Core Idea

Config experimental que habilita detecção de conectividade e retry automático de navegação, prefetch e Server Actions falhados por causa de rede, além de expor o hook useOffline para Client Components lerem o estado atual de conectividade.

Key Concepts

  • experimental.useOffline: boolean; ativa listeners de eventos offline/online do browser, detecção de falha de rede em navegação/prefetch/Server Actions, polling com backoff, retry automático, e disponibiliza o hook useOffline via next/offline.
  • Entrada no estado offline: por evento do browser (window.addEventListener('offline', ...)) OU por fetch falho (erro não-abort/não-timeout numa requisição de navegação/prefetch/Server Action), cobrindo o caso em que navigator.onLine ainda diz true mas a origem está inalcançável.
  • Connectivity check: uma requisição HEAD para a URL da página atual com header RSC, abortada após 200ms. Conta como "online" se: (1) o fetch resolve normalmente, ou (2) o timeout de 200ms aborta (indicando handshake TCP bem-sucedido, já que uma requisição realmente offline falha quase instantaneamente).
  • Backoff: escalonado (não exponencial), teto de 3s: tentativa 1 = 500ms, 2 = 1s, 3 = 2s, 4+ = 3s. O evento online do browser interrompe a espera atual e roda um check imediatamente.
  • Retry de framework requests: enquanto offline, navegação/prefetch/Server Action esperam o próximo check de conectividade ter sucesso, depois rodam uma vez, sem backoff extra.

Code Examples

const nextConfig: NextConfig = {
  experimental: {
    useOffline: true,
  },
}
  • O que demonstra: habilitação mínima da feature.

Reference Tables

AttemptDelay before next check
1500 ms
21 s
32 s
4 and after3 s
VersionChanges
v16.x.0experimental.useOffline configuration option introduced.

Anti-patterns

  • Assumir que isso gera flood de tráfego no reconnect: a doc detalha o contrário: polling é single-request por vez com teto de 3s, e ao reconectar, cada navegação/Server Action pendente dispara só uma vez (só a última navegação pendente é mantida).

Key Takeaways

  1. O polling nunca desiste sozinho, continua indefinidamente até um check ter sucesso ou a página descarregar.
  2. Fetches que falham enquanto offline não chegam nem a sair do browser (rejeitam na camada de rede local), então não geram tráfego real no servidor.
  3. Prefetches continuam passando pela fila normal de prefetch, não disparam todos de uma vez ao reconectar.
  4. Habilitar essa flag também expõe o hook useOffline para uso em Client Components.

Connects To

  • useOffline (hook, api-reference/functions/use-offline): API do hook para ler o estado offline em Client Components.
  • PWAs (guides/progressive-web-apps): contexto mais amplo de app offline-capable.
AnterioruseLightningcssPróximouseTypeScriptCli