Padrões do Nuxt 4

Use ao construir ou depurar aplicativos Nuxt 4 com SSR, renderização híbrida, regras de rota ou busca de dados em nível de página.

Quando Ativar

• Inconsistências de hidratação entre o HTML do servidor e o estado do cliente
• Decisões de renderização em nível de rota, como pré-renderização, SWR, ISR ou seções apenas do cliente
• Trabalho de performance em torno de carregamento preguiçoso (lazy loading), hidratação preguiçosa (lazy hydration) ou tamanho do payload
• Busca de dados de página ou componente com useFetch, useAsyncData ou $fetch
• Problemas de roteamento do Nuxt ligados a parâmetros de rota, middleware ou diferenças SSR/cliente

Segurança de Hidratação

• Mantenha a primeira renderização determinística. Não coloque Date.now(), Math.random(), APIs exclusivas do navegador ou leituras de armazenamento diretamente no estado do template renderizado pelo SSR.
• Mova a lógica exclusiva do navegador para trás de onMounted(), import.meta.client, ClientOnly ou um componente .client.vue quando o servidor não puder produzir o mesmo markup.
• Use o composable useRoute() do Nuxt, não o de vue-router.
• Não use route.fullPath para controlar o markup renderizado pelo SSR. Fragmentos de URL são exclusivos do cliente, o que pode criar inconsistências de hidratação.
• Trate ssr: false como uma saída de emergência para áreas verdadeiramente exclusivas do navegador, não uma correção padrão para inconsistências.

Busca de Dados

• Prefira await useFetch() para leituras de API seguras para SSR em páginas e componentes. Ele encaminha dados buscados pelo servidor para o payload do Nuxt e evita uma segunda busca na hidratação.
• Use useAsyncData() quando o fetcher não for uma simples chamada $fetch(), quando precisar de uma chave personalizada ou quando estiver compondo várias fontes assíncronas.
• Dê a useAsyncData() uma chave estável para reutilização de cache e comportamento de atualização previsível.
• Mantenha os manipuladores de useAsyncData() livres de efeitos colaterais. Eles podem ser executados durante o SSR e a hidratação.
• Use $fetch() para escritas acionadas pelo usuário ou ações exclusivas do cliente, não para dados de página de nível superior que devem ser hidratados a partir do SSR.
• Use lazy: true, useLazyFetch() ou useLazyAsyncData() para dados não críticos que não devem bloquear a navegação. Lide com status === 'pending' na UI.
• Use server: false apenas para dados que não são necessários para SEO ou para a primeira pintura (first paint).
• Reduza o tamanho do payload com pick e prefira payloads mais rasos quando a reatividade profunda for desnecessária.

const route = useRoute()

const { data: article, status, error, refresh } = await useAsyncData(
  () => `article:${route.params.slug}`,
  () => $fetch(`/api/articles/${route.params.slug}`),
)

const { data: comments } = await useFetch(`/api/articles/${route.params.slug}/comments`, {
  lazy: true,
  server: false,
})

Regras de Rota

Prefira routeRules em nuxt.config.ts para estratégia de renderização e cache:

export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
    '/products/**': { swr: 3600 },
    '/blog/**': { isr: true },
    '/admin/**': { ssr: false },
    '/api/**': { cache: { maxAge: 60 * 60 } },
  },
})

• prerender: HTML estático no momento da compilação (build time)
• swr: serve conteúdo em cache e revalida em segundo plano
• isr: regeneração estática incremental em plataformas suportadas
• ssr: false: rota renderizada pelo cliente
• cache ou redirect: comportamento de resposta em nível do Nitro

Escolha regras de rota por grupo de rotas, não globalmente. Páginas de marketing, catálogos, dashboards e APIs geralmente precisam de estratégias diferentes.

Carregamento Preguiçoso e Performance

• O Nuxt já faz code-splitting de páginas por rota. Mantenha os limites de rota significativos antes de micro-otimizar divisões de componentes.
• Use o prefixo Lazy para importar dinamicamente componentes não críticos.
• Renderize condicionalmente componentes preguiçosos com v-if para que o chunk não seja carregado até que a UI realmente precise dele.
• Use hidratação preguiçosa para UI interativa abaixo da dobra (below-the-fold) ou não crítica.

<template>
  <LazyRecommendations v-if="showRecommendations" />
  <LazyProductGallery hydrate-on-visible />
</template>

• Para estratégias personalizadas, use defineLazyHydrationComponent() com uma estratégia de visibilidade ou ociosidade (idle).
• A hidratação preguiçosa do Nuxt funciona em componentes de arquivo único (single-file components). Passar novas props para um componente hidratado preguiçosamente acionará a hidratação imediatamente.
• Use NuxtLink para navegação interna para que o Nuxt possa pré-buscar componentes de rota e payloads gerados.

Lista de Verificação de Revisão

• A primeira renderização SSR e a renderização do cliente hidratada produzem o mesmo markup
• Os dados da página usam useFetch ou useAsyncData, não $fetch de nível superior
• Dados não críticos são preguiçosos e têm UI de carregamento explícita
• As regras de rota correspondem aos requisitos de SEO e frescor da página
• Ilhas interativas pesadas são carregadas preguiçosamente ou hidratadas preguiçosamente