Fetching Condicional e Dependente

Q: Quais valores posso passar como chave para impedir o SWR de buscar dados?

O SWR pula o fetch quando a chave é null, undefined, false ou uma string vazia "". Qualquer um desses valores falsy impedirá a requisição.

Q: O que o useSWR retorna quando a chave é null?

Ele retorna { data: undefined, error: undefined, isLoading: false }. Nenhuma busca é feita -- isLoading é false porque não há nada para carregar.

Q: Como o TypeScript lida com o tipo de dados quando a chave pode ser null?

O tipo de dados permanece Data | undefined, pois o fetch pode ainda não ter sido executado. Use um tipo de união ou genérico para mantê-lo limpo:

Q: Quando a chave transita de null para um valor real, o que acontece com isLoading?

isLoading se torna true para essa transição enquanto o SWR busca dados para a chave recém-truthy. Planeje sua UI de carregamento para levar em conta essa mudança de estado.

Receita

Passe null ou um valor falsy como chave para impedir o SWR de buscar dados. Use isso para aguardar dependências, controlar requisições com base em autenticação ou encadear buscas sequenciais.

"use client";
 
import useSWR from "swr";
 
function UserProjects({ userId }: { userId: string | null }) {
  // Não buscará até que userId esteja disponível
  const { data } = useSWR(userId ? `/api/users/${userId}/projects` : null, fetcher);
 
  return <div>{data?.length ?? 0} projetos</div>;
}

Exemplo Funcionando

"use client";
 
import useSWR from "swr";
 
const fetcher = (url: string) => fetch(url).then((r) => r.json());
 
interface User {
  id: string;
  name: string;
  teamId: string;
}
 
interface Team {
  id: string;
  name: string;
  members: string[];
}
 
export default function UserTeamInfo({ userId }: { userId: string }) {
  // Passo 1: Buscar usuário
  const { data: user, isLoading: userLoading } = useSWR<User>(
    `/api/users/${userId}`,
    fetcher
  );
 
  // Passo 2: Buscar time apenas após o usuário carregar (fetching dependente)
  const { data: team, isLoading: teamLoading } = useSWR<Team>(
    user ? `/api/teams/${user.teamId}` : null,
    fetcher
  );
 
  if (userLoading) return <p>Carregando usuário...</p>;
  if (teamLoading) return <p>Carregando time para {user?.name}...</p>;
 
  return (
    <div>
      <p>{user?.name} pertence ao time {team?.name}</p>
      <p>O time tem {team?.members.length} membros</p>
    </div>
  );
}

Análise Detalhada

Como Funciona

Quando a chave é null, undefined, false ou "", o SWR pula o fetch inteiramente e retorna { data: undefined, error: undefined, isLoading: false }.
Esta é a maneira idiomática de implementar fetching dependente (waterfall) - a chave da segunda requisição é derivada dos dados da primeira requisição.
Assim que a chave se torna truthy, o SWR dispara o fetch imediatamente.
A forma de função de chave () => condition ? key : null também é suportada e avaliada em cada renderização.

Variações

Chave como função:

const { data } = useSWR(
  () => (isLoggedIn ? `/api/profile` : null),
  fetcher
);

Múltiplas dependências:

const { data: user } = useSWR("/api/me", fetcher);
const { data: org } = useSWR(user ? `/api/orgs/${user.orgId}` : null, fetcher);
const { data: billing } = useSWR(
  user && org ? `/api/orgs/${org.id}/billing` : null,
  fetcher
);

Condicional com chave de array:

const { data } = useSWR(
  token ? ["/api/data", token] : null,
  ([url, token]) =>
    fetch(url, { headers: { Authorization: `Bearer ${token}` } }).then((r) => r.json())
);

Lançar erro na função de chave para pausar:

// Lançar um erro dentro da função de chave também pausa o fetch
const { data } = useSWR(
  () => `/api/users/${userId ?? throwUndefined()}`,
  fetcher
);
 
function throwUndefined(): never {
  throw new Error("não está pronto");
}

Notas de TypeScript

Ao usar chaves condicionais, o tipo dos dados permanece Data | undefined, pois o fetch pode ainda não ter sido executado.
Se a chave for null, o TypeScript infere o tipo da chave como null. Use um tipo de união ou genérico para mantê-lo limpo.

const { data } = useSWR<Team>(
  user ? `/api/teams/${user.teamId}` : null,
  fetcher
);
// data: Team | undefined

Armadilhas

O fetching dependente cria um waterfall. Cada requisição encadeada deve esperar pela anterior. Mantenha as cadeias de dependência curtas para evitar lentidão no carregamento das páginas.
Quando a chave transita de null para um valor real, isLoading se torna true para essa transição. Planeje sua UI de carregamento de acordo.
Se você usar uma função de chave que lança um erro, o SWR a trata da mesma forma que uma chave null. No entanto, erros lançados na função de chave são capturados silenciosamente e não aparecem em error.
Não confunda fetching condicional (chave null) com tratamento de erros. Uma chave null significa "não buscar", não "falha ao buscar".

Alternativas

Abordagem	Prós	Contras
Chave null (SWR)	Declarativa, gatilho automático na mudança	Cria waterfall para fetches dependentes
Opção `enabled` (React Query)	Flag booleana explícita	Não disponível nativamente no SWR
Guarda `useEffect`	Padrão imperativo familiar	Perde os benefícios de cache e dedup do SWR
Join no lado do servidor	Requisição única, sem waterfall	Requer mudanças na API, menos flexível

FAQs

Quais valores posso passar como chave para impedir o SWR de buscar dados?

O SWR pula o fetch quando a chave é null, undefined, false ou uma string vazia "". Qualquer um desses valores falsy impedirá a requisição.

O que o useSWR retorna quando a chave é null?

Ele retorna { data: undefined, error: undefined, isLoading: false }. Nenhuma busca é feita -- isLoading é false porque não há nada para carregar.

Como encadeio fetches sequenciais (dependentes) com SWR?

Derive a chave da segunda requisição dos dados da primeira requisição:

const { data: user } = useSWR("/api/me", fetcher);
const { data: team } = useSWR(
  user ? `/api/teams/${user.teamId}` : null,
  fetcher
);

O fetch do time só executa após user estar disponível.

Posso passar uma função como chave para useSWR para fetching condicional?

Sim. O SWR avalia uma função de chave em cada renderização:

const { data } = useSWR(
  () => (isLoggedIn ? `/api/profile` : null),
  fetcher
);

Armadilha: O fetching dependente cria um waterfall, e como devo lidar com isso?

Sim. Cada requisição encadeada espera pela anterior. Mantenha as cadeias de dependência curtas (2-3 no máximo) para evitar lentidão no carregamento das páginas. Se possível, combine os dados em um único endpoint de API no lado do servidor.

O que acontece quando uma função de chave lança um erro?

O SWR trata um erro lançado dentro da função de chave da mesma forma que uma chave null -- ele pausa o fetch. No entanto, o erro é capturado silenciosamente e não aparece no valor de retorno error.

Como uso fetching condicional com chaves de array?

const { data } = useSWR(
  token ? ["/api/data", token] : null,
  ([url, token]) =>
    fetch(url, {
      headers: { Authorization: `Bearer ${token}` },
    }).then((r) => r.json())
);

Armadilha: Uma chave null é o mesmo que um fetch falho?

Não. Uma chave null significa "não buscar". Não é um estado de erro. error permanece undefined e isLoading é false. Não confunda fetching condicional com tratamento de erros.

Como o TypeScript lida com o tipo de dados quando a chave pode ser null?

O tipo de dados permanece Data | undefined, pois o fetch pode ainda não ter sido executado. Use um tipo de união ou genérico para mantê-lo limpo:

const { data } = useSWR<Team>(
  user ? `/api/teams/${user.teamId}` : null,
  fetcher
);
// data: Team | undefined

Quando a chave transita de null para um valor real, o que acontece com isLoading?

isLoading se torna true para essa transição enquanto o SWR busca dados para a chave recém-truthy. Planeje sua UI de carregamento para levar em conta essa mudança de estado.

Como o fetching condicional do SWR se compara à opção `enabled` do React Query?

O SWR usa chaves null/falsy para impedir o fetch, enquanto o React Query tem uma opção booleana explícita enabled. A abordagem do SWR é declarativa e baseada em chave; a do React Query é mais explícita, mas não disponível nativamente no SWR.

Links Relacionados

Receita

Passe null ou um valor falsy como chave para impedir o SWR de buscar dados. Use isso para aguardar dependências, controlar requisições com base em autenticação ou encadear buscas sequenciais.

"use client";
 
import useSWR from "swr";
 
function UserProjects({ userId }: { userId: string | null }) {
  // Não buscará até que userId esteja disponível
  const { data } = useSWR(userId ? `/api/users/${userId}/projects` : null, fetcher);
 
  return <div>{data?.length ?? 0} projetos</div>;
}

Exemplo Funcionando

"use client";
 
import useSWR from "swr";
 
const fetcher = (url: string) => fetch(url).then((r) => r.json());
 
interface User {
  id: string;
  name: string;
  teamId: string;
}
 
interface Team {
  id: string;
  name: string;
  members: string[];
}
 
export default function UserTeamInfo({ userId }: { userId: string }) {
  // Passo 1: Buscar usuário
  const { data: user, isLoading: userLoading } = useSWR<User>(
    `/api/users/${userId}`,
    fetcher
  );
 
  // Passo 2: Buscar time apenas após o usuário carregar (fetching dependente)
  const { data: team, isLoading: teamLoading } = useSWR<Team>(
    user ? `/api/teams/${user.teamId}` : null,
    fetcher
  );
 
  if (userLoading) return <p>Carregando usuário...</p>;
  if (teamLoading) return <p>Carregando time para {user?.name}...</p>;
 
  return (
    <div>
      <p>{user?.name} pertence ao time {team?.name}</p>
      <p>O time tem {team?.members.length} membros</p>
    </div>
  );
}

Análise Detalhada

Como Funciona

Quando a chave é null, undefined, false ou "", o SWR pula o fetch inteiramente e retorna { data: undefined, error: undefined, isLoading: false }.
Esta é a maneira idiomática de implementar fetching dependente (waterfall) - a chave da segunda requisição é derivada dos dados da primeira requisição.
Assim que a chave se torna truthy, o SWR dispara o fetch imediatamente.
A forma de função de chave () => condition ? key : null também é suportada e avaliada em cada renderização.

Variações

Chave como função:

const { data } = useSWR(
  () => (isLoggedIn ? `/api/profile` : null),
  fetcher
);

Múltiplas dependências:

const { data: user } = useSWR("/api/me", fetcher);
const { data: org } = useSWR(user ? `/api/orgs/${user.orgId}` : null, fetcher);
const { data: billing } = useSWR(
  user && org ? `/api/orgs/${org.id}/billing` : null,
  fetcher
);

Condicional com chave de array:

const { data } = useSWR(
  token ? ["/api/data", token] : null,
  ([url, token]) =>
    fetch(url, { headers: { Authorization: `Bearer ${token}` } }).then((r) => r.json())
);

Lançar erro na função de chave para pausar:

// Lançar um erro dentro da função de chave também pausa o fetch
const { data } = useSWR(
  () => `/api/users/${userId ?? throwUndefined()}`,
  fetcher
);
 
function throwUndefined(): never {
  throw new Error("não está pronto");
}

Notas de TypeScript

Ao usar chaves condicionais, o tipo dos dados permanece Data | undefined, pois o fetch pode ainda não ter sido executado.
Se a chave for null, o TypeScript infere o tipo da chave como null. Use um tipo de união ou genérico para mantê-lo limpo.

const { data } = useSWR<Team>(
  user ? `/api/teams/${user.teamId}` : null,
  fetcher
);
// data: Team | undefined

Armadilhas

O fetching dependente cria um waterfall. Cada requisição encadeada deve esperar pela anterior. Mantenha as cadeias de dependência curtas para evitar lentidão no carregamento das páginas.
Quando a chave transita de null para um valor real, isLoading se torna true para essa transição. Planeje sua UI de carregamento de acordo.
Se você usar uma função de chave que lança um erro, o SWR a trata da mesma forma que uma chave null. No entanto, erros lançados na função de chave são capturados silenciosamente e não aparecem em error.
Não confunda fetching condicional (chave null) com tratamento de erros. Uma chave null significa "não buscar", não "falha ao buscar".

Alternativas

Abordagem	Prós	Contras
Chave null (SWR)	Declarativa, gatilho automático na mudança	Cria waterfall para fetches dependentes
Opção `enabled` (React Query)	Flag booleana explícita	Não disponível nativamente no SWR
Guarda `useEffect`	Padrão imperativo familiar	Perde os benefícios de cache e dedup do SWR
Join no lado do servidor	Requisição única, sem waterfall	Requer mudanças na API, menos flexível

FAQs

Quais valores posso passar como chave para impedir o SWR de buscar dados?

O SWR pula o fetch quando a chave é null, undefined, false ou uma string vazia "". Qualquer um desses valores falsy impedirá a requisição.

O que o useSWR retorna quando a chave é null?

Ele retorna { data: undefined, error: undefined, isLoading: false }. Nenhuma busca é feita -- isLoading é false porque não há nada para carregar.

Como encadeio fetches sequenciais (dependentes) com SWR?

Derive a chave da segunda requisição dos dados da primeira requisição:

const { data: user } = useSWR("/api/me", fetcher);
const { data: team } = useSWR(
  user ? `/api/teams/${user.teamId}` : null,
  fetcher
);

O fetch do time só executa após user estar disponível.

Posso passar uma função como chave para useSWR para fetching condicional?

Sim. O SWR avalia uma função de chave em cada renderização:

const { data } = useSWR(
  () => (isLoggedIn ? `/api/profile` : null),
  fetcher
);

Armadilha: O fetching dependente cria um waterfall, e como devo lidar com isso?

O que acontece quando uma função de chave lança um erro?

Como uso fetching condicional com chaves de array?

const { data } = useSWR(
  token ? ["/api/data", token] : null,
  ([url, token]) =>
    fetch(url, {
      headers: { Authorization: `Bearer ${token}` },
    }).then((r) => r.json())
);

Armadilha: Uma chave null é o mesmo que um fetch falho?

Não. Uma chave null significa "não buscar". Não é um estado de erro. error permanece undefined e isLoading é false. Não confunda fetching condicional com tratamento de erros.

Como o TypeScript lida com o tipo de dados quando a chave pode ser null?

O tipo de dados permanece Data | undefined, pois o fetch pode ainda não ter sido executado. Use um tipo de união ou genérico para mantê-lo limpo:

const { data } = useSWR<Team>(
  user ? `/api/teams/${user.teamId}` : null,
  fetcher
);
// data: Team | undefined

Quando a chave transita de null para um valor real, o que acontece com isLoading?

isLoading se torna true para essa transição enquanto o SWR busca dados para a chave recém-truthy. Planeje sua UI de carregamento para levar em conta essa mudança de estado.

Como o fetching condicional do SWR se compara à opção `enabled` do React Query?

Fetching Condicional e Dependente

Buscar na documentação

Fetching Condicional e Dependente