Frontend Academy · Aula

useFetch e useAsyncData

Obter dados do servidor com useFetch e useAsyncData, lidar com estados pendentes e de erro e compreender como o Nuxt hidrata o cliente.

useFetch e useAsyncData é uma aula grátis de Frontend Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Frontend Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Frontend Academy inclui 4 aulas no total.

Busca de dados no Nuxt 3

O Nuxt oferece dois composables principais para buscar dados: useFetch (baseado em URL, chama fetch internamente) e useAsyncData (aceita qualquer função assíncrona, com uma chave exclusiva para armazenamento em cache e eliminação de duplicatas).

useFetch — o jeito rápido

Informe uma URL — o Nuxt faz a busca durante o SSR, hidrata no cliente e impede que o cliente faça uma nova busca durante a hidratação.

<script setup>
const { data: posts, pending, error } = await useFetch('/api/posts');
</script>

<template>
  <div v-if="pending">Loading...</div>
  <div v-else-if="error">{{ error.message }}</div>
  <ul v-else>
    <li v-for="p in posts" :key="p.id">{{ p.title }}</li>
  </ul>
</template>

Por que não há uma segunda busca durante a hidratação?

O Nuxt serializa os dados buscados na carga útil do HTML gerado pelo SSR. No cliente, useFetch hidrata a partir dessa carga — não há uma segunda chamada de rede. Essa é a principal otimização do SSR.

useAsyncData — assíncrono e flexível

Use quando a busca não for uma URL simples — consultas ao banco de dados, lógica personalizada ou requisições em várias etapas.

<script setup>
const { data: user } = await useAsyncData('user-profile', async () => {
  const me = await $fetch('/api/me');
  const stats = await $fetch(`/api/users/${me.id}/stats`);
  return { ...me, stats };
});
</script>

A chave do cache é importante

O primeiro argumento de useAsyncData é uma chave exclusiva do cache. A mesma chave compartilhada entre componentes elimina duplicações e reutiliza o resultado. Chaves diferentes = buscas independentes.

// Two components calling useFetch('/api/posts') share one request
// Two components calling useFetch('/api/posts', { key: 'a' }) and { key: 'b' } fetch twice

Atualização e carregamento tardio

Ambos os composables retornam refresh() para fazer uma nova busca e aceitam { lazy: true } para evitar o bloqueio do SSR (os dados são carregados depois que a página é renderizada).

const { data, refresh } = await useFetch('/api/posts');

async function onSave() {
  await $fetch('/api/posts', { method: 'POST', body: newPost });
  await refresh();
}

// Or lazy mode:
const { data, pending } = useFetch('/api/posts', { lazy: true });

Observação e URLs reativas

Passe uma função para a URL — ela será reativa. Uma nova busca será feita quando as dependências mudarem.

<script setup>
const page = ref(1);
const { data } = await useFetch(() => `/api/posts?page=${page.value}`);
// Changing page.value re-runs the fetch
</script>

Opções da requisição

useFetch aceita as mesmas opções que fetch — método, body, cabeçalhos, além de opções específicas do Nuxt, como default e transform.

const { data } = await useFetch('/api/posts', {
  method: 'POST',
  body: { title: 'Hello' },
  headers: { 'X-Custom': '1' },
  transform: (raw) => raw.items.map(transformItem),
  default: () => []
});

$fetch — busca imperativa

$fetch é o buscador universal do Nuxt (usa ofetch internamente). Não há rastreamento automático da hidratação. Use-o em manipuladores de eventos e mutações.

async function deletePost(id) {
  await $fetch(`/api/posts/${id}`, { method: 'DELETE' });
  await refresh();
}

Tratamento de erros

Lance um erro dentro do manipulador de busca para torná-lo visível. As páginas podem exibir uma página de erro personalizada com ~/error.vue.

// error.vue at project root
<script setup>
const props = defineProps<{ error: any }>();
</script>

<template>
  <div>
    <h1>{{ error.statusCode }}</h1>
    <p>{{ error.message }}</p>
    <button @click="clearError({ redirect: '/' })">Home</button>
  </div>
</template>

Autenticação e cookies

useFetch encaminha cookies automaticamente durante o SSR, portanto as requisições autenticadas funcionam tanto no servidor quanto no cliente sem tratamento manual de cookies.

useFetch vs useAsyncData — quando usar?

useFetch: requisições simples baseadas em URL (95% dos casos). useAsyncData: lógica assíncrona personalizada, composição em várias etapas e fontes que não são URLs (banco de dados por meio de server/utils).

Verificação rápida

Por que o useFetch no Nuxt 3 impede uma requisição de rede duplicada quando a página é hidratada no cliente?

Recapitulação: useFetch e useAsyncData

useFetch: baseado em URL, o caso de 95%. useAsyncData: lógica assíncrona personalizada com uma chave de cache exclusiva. Ambos são hidratados a partir da carga útil do SSR (sem uma segunda solicitação). refresh() para buscar novamente, lazy:true para evitar bloquear o SSR. URLs reativas acionam uma nova busca. $fetch para mutações imperativas. error.vue trata os erros. Os cookies são encaminhados automaticamente durante o SSR.

Perguntas Frequentes

A aula “useFetch e useAsyncData” é grátis?

Sim — o texto completo de “useFetch e useAsyncData” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Frontend Academy, atualize para CoddyKit PRO. O curso de Frontend Academy inclui 4 aulas no total.

O que vou aprender em “useFetch e useAsyncData”?

Obter dados do servidor com useFetch e useAsyncData, lidar com estados pendentes e de erro e compreender como o Nuxt hidrata o cliente. Você pratica Frontend Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Frontend Academy?

Nenhuma experiência prévia é necessária. Frontend Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “useFetch e useAsyncData”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Frontend Academy?

Sim. Cada aula de Frontend Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

Roteamento baseado em ficheiros e importações automáticas
useFetch e useAsyncData
Módulos Nuxt: imagens, autenticação e i18n
Implementação: estática vs SSR

← Voltar para Frontend Academy