Configuração e Instalação do SWR

Q: Por que o arquivo do provedor SWRConfig precisa de "use client" no Next.js App Router?

SWRConfig usa React Context internamente, que é uma API do lado do cliente. Sem "use client", o Next.js trata o arquivo como um Server Component e lança um erro em tempo de execução quando o Context é usado.

Q: Como os provedores SWRConfig aninhados mesclam seus valores?

Valores internos de SWRConfig se mesclam e substituem valores externos. Por exemplo, um provedor interno pode definir refreshInterval enquanto herda o fetcher do provedor externo.

Q: O que acontece se o fetcher não lançar erro em respostas HTTP não 2xx?

O SWR tratará a resposta como dados bem-sucedidos. O valor error será sempre undefined, mesmo em respostas 404 ou 500. Sempre verifique res.ok no seu fetcher e lance um erro se for falso.

Q: Como posso acessar os valores do SWRConfig pai ao definir uma configuração aninhada?

Passe uma função em vez de um objeto para a prop value:

Q: É seguro definir refreshInterval globalmente em SWRConfig?

Funciona, mas aplica polling a todos os hooks useSWR na árvore. Prefira definir refreshInterval por hook, a menos que você realmente precise que todas as consultas façam polling na mesma taxa.

Q: Como tipar o objeto de valor de SWRConfig em TypeScript?

Importe SWRConfiguration de swr e use-o como tipo:

Q: Qual tipo TypeScript a prop de valor de SWRConfig aceita?

Aceita Partial ou uma função (parentConfig: SWRConfiguration) => SWRConfiguration que recebe a configuração pai e retorna uma nova.

Q: Armadilha: Qual é um erro comum ao omitir o fetcher de chamadas individuais useSWR?

Se não houver um provedor SWRConfig envolvendo o componente (ou se o provedor não definir um fetcher), useSWR não terá um fetcher e silenciosamente nunca buscará dados. Sempre garanta que um provedor com um fetcher exista acima dos seus componentes.

Receita

Instale o SWR, envolva seu aplicativo com SWRConfig e defina padrões globais para que cada chamada useSWR herde um fetcher e opções compartilhados.

npm install swr

// app/providers.tsx
"use client";
 
import { SWRConfig } from "swr";
 
const fetcher = (url: string) => fetch(url).then((res) => res.json());
 
export function SWRProvider({ children }: { children: React.ReactNode }) {
  return (
    <SWRConfig
      value={{
        fetcher,
        revalidateOnFocus: true,
        dedupingInterval: 2000,
      }}
    >
      {children}
    </SWRConfig>
  );
}

// app/layout.tsx
import { SWRProvider } from "./providers";
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SWRProvider>{children}</SWRProvider>
      </body>
    </html>
  );
}

Exemplo de Funcionamento

"use client";
 
import useSWR from "swr";
 
function UserProfile({ userId }: { userId: string }) {
  // fetcher é herdado de SWRConfig
  const { data, error, isLoading } = useSWR(`/api/users/${userId}`);
 
  if (isLoading) return <div>Carregando...</div>;
  if (error) return <div>Falha ao carregar</div>;
 
  return <div>Olá, {data.name}!</div>;
}

Análise Detalhada

Como Funciona

SWRConfig usa React Context internamente para propagar valores de configuração pela árvore de componentes.
Qualquer chamada useSWR sem um fetcher explícito recorrerá ao fetcher do provedor SWRConfig mais próximo.
Múltiplos provedores SWRConfig podem ser aninhados; valores internos se mesclam e substituem valores externos.
O dedupingInterval impede requisições duplicadas para a mesma chave dentro dos milissegundos especificados.
revalidateOnFocus aciona uma revalidação em segundo plano quando a aba do navegador recupera o foco.

Variações

Fetcher customizado com cabeçalhos:

const authedFetcher = (url: string) =>
  fetch(url, {
    headers: { Authorization: `Bearer ${getToken()}` },
  }).then((res) => {
    if (!res.ok) throw new Error("Falha ao buscar");
    return res.json();
  });

Configuração aninhada com substituição:

<SWRConfig value={{ fetcher: globalFetcher }}>
  <SWRConfig value={{ refreshInterval: 3000 }}>
    {/* Componentes aqui recebem globalFetcher + 3s de refresh */}
  </SWRConfig>
</SWRConfig>

Configuração funcional (acessa o pai):

<SWRConfig
  value={(parentConfig) => ({
    ...parentConfig,
    refreshInterval: 5000,
  })}
>
  {children}
</SWRConfig>

Notas de TypeScript

SWRConfig aceita value tipado como Partial<SWRConfiguration> ou uma função que retorna um.
Importe SWRConfiguration de swr para tipar objetos de configuração explicitamente.

import type { SWRConfiguration } from "swr";
 
const config: SWRConfiguration = {
  fetcher: (url: string) => fetch(url).then((r) => r.json()),
  revalidateOnFocus: false,
};

Armadilhas

Esquecer de adicionar "use client" no arquivo do provedor no Next.js App Router causará um erro em tempo de execução porque SWRConfig usa React Context.
Se o seu fetcher lançar um erro em respostas não 2xx, o SWR tratará isso como um erro. Se ele não lançar um erro, error sempre será undefined, mesmo em respostas 404.
dedupingInterval não é o mesmo que cache. Ele apenas deduplica requisições em andamento dentro da janela de intervalo.
Definir refreshInterval no nível global se aplica a todos os hooks. Prefira definir por hook, a menos que você realmente precise de polling global.

Alternativas

Abordagem	Prós	Contras
SWRConfig Global	Configuração única, padrões consistentes	Todos os hooks compartilham a configuração; pode ser muito amplo
Configuração por hook	Controle granular por consulta	Declarações repetitivas de fetcher
Wrapper de hook customizado	Lógica centralizada com flexibilidade	Camada de abstração extra

FAQs

Por que o arquivo do provedor SWRConfig precisa de "use client" no Next.js App Router?

SWRConfig usa React Context internamente, que é uma API do lado do cliente. Sem "use client", o Next.js trata o arquivo como um Server Component e lança um erro em tempo de execução quando o Context é usado.

O que a opção dedupingInterval realmente faz?

Ele deduplica requisições em andamento para a mesma chave dentro da janela de milissegundos especificada (padrão de 2000ms).
Se dois componentes montarem e chamarem useSWR com a mesma chave dentro dessa janela, apenas uma requisição de rede será feita.
Não é o mesmo que cache -- ele apenas impede requisições duplicadas concorrentes.

Como os provedores SWRConfig aninhados mesclam seus valores?

Valores internos de SWRConfig se mesclam e substituem valores externos. Por exemplo, um provedor interno pode definir refreshInterval enquanto herda o fetcher do provedor externo.

O que acontece se o fetcher não lançar erro em respostas HTTP não 2xx?

O SWR tratará a resposta como dados bem-sucedidos. O valor error será sempre undefined, mesmo em respostas 404 ou 500. Sempre verifique res.ok no seu fetcher e lance um erro se for falso.

Como posso acessar os valores do SWRConfig pai ao definir uma configuração aninhada?

Passe uma função em vez de um objeto para a prop value:

<SWRConfig
  value={(parentConfig) => ({
    ...parentConfig,
    refreshInterval: 5000,
  })}
>
  {children}
</SWRConfig>

É seguro definir refreshInterval globalmente em SWRConfig?

Funciona, mas aplica polling a todos os hooks useSWR na árvore. Prefira definir refreshInterval por hook, a menos que você realmente precise que todas as consultas façam polling na mesma taxa.

Como tipar o objeto de valor de SWRConfig em TypeScript?

Importe SWRConfiguration de swr e use-o como tipo:

import type { SWRConfiguration } from "swr";
 
const config: SWRConfiguration = {
  fetcher: (url: string) => fetch(url).then((r) => r.json()),
  revalidateOnFocus: false,
};

Qual tipo TypeScript a prop de valor de SWRConfig aceita?

Aceita Partial<SWRConfiguration> ou uma função (parentConfig: SWRConfiguration) => SWRConfiguration que recebe a configuração pai e retorna uma nova.

Posso adicionar cabeçalhos de autorização ao fetcher global?

Sim. Defina um fetcher customizado que inclua cabeçalhos:

const authedFetcher = (url: string) =>
  fetch(url, {
    headers: { Authorization: `Bearer ${getToken()}` },
  }).then((res) => {
    if (!res.ok) throw new Error("Falha ao buscar");
    return res.json();
  });

Armadilha: Qual é um erro comum ao omitir o fetcher de chamadas individuais useSWR?

Se não houver um provedor SWRConfig envolvendo o componente (ou se o provedor não definir um fetcher), useSWR não terá um fetcher e silenciosamente nunca buscará dados. Sempre garanta que um provedor com um fetcher exista acima dos seus componentes.

Onde o SWRProvider deve ser colocado em um projeto Next.js App Router?

Envolva-o em {children} no seu app/layout.tsx raiz para que todas as páginas e componentes herdem a configuração compartilhada.

Links Relacionados

Receita

Instale o SWR, envolva seu aplicativo com SWRConfig e defina padrões globais para que cada chamada useSWR herde um fetcher e opções compartilhados.

npm install swr

// app/providers.tsx
"use client";
 
import { SWRConfig } from "swr";
 
const fetcher = (url: string) => fetch(url).then((res) => res.json());
 
export function SWRProvider({ children }: { children: React.ReactNode }) {
  return (
    <SWRConfig
      value={{
        fetcher,
        revalidateOnFocus: true,
        dedupingInterval: 2000,
      }}
    >
      {children}
    </SWRConfig>
  );
}

// app/layout.tsx
import { SWRProvider } from "./providers";
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SWRProvider>{children}</SWRProvider>
      </body>
    </html>
  );
}

Exemplo de Funcionamento

"use client";
 
import useSWR from "swr";
 
function UserProfile({ userId }: { userId: string }) {
  // fetcher é herdado de SWRConfig
  const { data, error, isLoading } = useSWR(`/api/users/${userId}`);
 
  if (isLoading) return <div>Carregando...</div>;
  if (error) return <div>Falha ao carregar</div>;
 
  return <div>Olá, {data.name}!</div>;
}

Análise Detalhada

Como Funciona

SWRConfig usa React Context internamente para propagar valores de configuração pela árvore de componentes.
Qualquer chamada useSWR sem um fetcher explícito recorrerá ao fetcher do provedor SWRConfig mais próximo.
Múltiplos provedores SWRConfig podem ser aninhados; valores internos se mesclam e substituem valores externos.
O dedupingInterval impede requisições duplicadas para a mesma chave dentro dos milissegundos especificados.
revalidateOnFocus aciona uma revalidação em segundo plano quando a aba do navegador recupera o foco.

Variações

Fetcher customizado com cabeçalhos:

const authedFetcher = (url: string) =>
  fetch(url, {
    headers: { Authorization: `Bearer ${getToken()}` },
  }).then((res) => {
    if (!res.ok) throw new Error("Falha ao buscar");
    return res.json();
  });

Configuração aninhada com substituição:

<SWRConfig value={{ fetcher: globalFetcher }}>
  <SWRConfig value={{ refreshInterval: 3000 }}>
    {/* Componentes aqui recebem globalFetcher + 3s de refresh */}
  </SWRConfig>
</SWRConfig>

Configuração funcional (acessa o pai):

<SWRConfig
  value={(parentConfig) => ({
    ...parentConfig,
    refreshInterval: 5000,
  })}
>
  {children}
</SWRConfig>

Notas de TypeScript

SWRConfig aceita value tipado como Partial<SWRConfiguration> ou uma função que retorna um.
Importe SWRConfiguration de swr para tipar objetos de configuração explicitamente.

import type { SWRConfiguration } from "swr";
 
const config: SWRConfiguration = {
  fetcher: (url: string) => fetch(url).then((r) => r.json()),
  revalidateOnFocus: false,
};

Armadilhas

Esquecer de adicionar "use client" no arquivo do provedor no Next.js App Router causará um erro em tempo de execução porque SWRConfig usa React Context.
Se o seu fetcher lançar um erro em respostas não 2xx, o SWR tratará isso como um erro. Se ele não lançar um erro, error sempre será undefined, mesmo em respostas 404.
dedupingInterval não é o mesmo que cache. Ele apenas deduplica requisições em andamento dentro da janela de intervalo.
Definir refreshInterval no nível global se aplica a todos os hooks. Prefira definir por hook, a menos que você realmente precise de polling global.

Alternativas

Abordagem	Prós	Contras
SWRConfig Global	Configuração única, padrões consistentes	Todos os hooks compartilham a configuração; pode ser muito amplo
Configuração por hook	Controle granular por consulta	Declarações repetitivas de fetcher
Wrapper de hook customizado	Lógica centralizada com flexibilidade	Camada de abstração extra

FAQs

Por que o arquivo do provedor SWRConfig precisa de "use client" no Next.js App Router?

O que a opção dedupingInterval realmente faz?

Ele deduplica requisições em andamento para a mesma chave dentro da janela de milissegundos especificada (padrão de 2000ms).
Se dois componentes montarem e chamarem useSWR com a mesma chave dentro dessa janela, apenas uma requisição de rede será feita.
Não é o mesmo que cache -- ele apenas impede requisições duplicadas concorrentes.

Como os provedores SWRConfig aninhados mesclam seus valores?

Valores internos de SWRConfig se mesclam e substituem valores externos. Por exemplo, um provedor interno pode definir refreshInterval enquanto herda o fetcher do provedor externo.

O que acontece se o fetcher não lançar erro em respostas HTTP não 2xx?

O SWR tratará a resposta como dados bem-sucedidos. O valor error será sempre undefined, mesmo em respostas 404 ou 500. Sempre verifique res.ok no seu fetcher e lance um erro se for falso.

Como posso acessar os valores do SWRConfig pai ao definir uma configuração aninhada?

Passe uma função em vez de um objeto para a prop value:

<SWRConfig
  value={(parentConfig) => ({
    ...parentConfig,
    refreshInterval: 5000,
  })}
>
  {children}
</SWRConfig>

É seguro definir refreshInterval globalmente em SWRConfig?

Funciona, mas aplica polling a todos os hooks useSWR na árvore. Prefira definir refreshInterval por hook, a menos que você realmente precise que todas as consultas façam polling na mesma taxa.

Como tipar o objeto de valor de SWRConfig em TypeScript?

Importe SWRConfiguration de swr e use-o como tipo:

import type { SWRConfiguration } from "swr";
 
const config: SWRConfiguration = {
  fetcher: (url: string) => fetch(url).then((r) => r.json()),
  revalidateOnFocus: false,
};

Qual tipo TypeScript a prop de valor de SWRConfig aceita?

Aceita Partial<SWRConfiguration> ou uma função (parentConfig: SWRConfiguration) => SWRConfiguration que recebe a configuração pai e retorna uma nova.

Posso adicionar cabeçalhos de autorização ao fetcher global?

Sim. Defina um fetcher customizado que inclua cabeçalhos:

const authedFetcher = (url: string) =>
  fetch(url, {
    headers: { Authorization: `Bearer ${getToken()}` },
  }).then((res) => {
    if (!res.ok) throw new Error("Falha ao buscar");
    return res.json();
  });

Armadilha: Qual é um erro comum ao omitir o fetcher de chamadas individuais useSWR?

Onde o SWRProvider deve ser colocado em um projeto Next.js App Router?

Envolva-o em {children} no seu app/layout.tsx raiz para que todas as páginas e componentes herdem a configuração compartilhada.

Configuração e Instalação do SWR

Buscar na documentação

Configuração e Instalação do SWR