Padrões Nuxt 4

O que Padrões Nuxt 4 faz?

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

• Incompatibilidades de hidratação entre o HTML do servidor e o estado do cliente
• Decisões de renderização em nível de rota, como prerender, SWR, ISR ou seções somente para cliente
• Trabalho de desempenho em torno de carregamento preguiçoso, hidratação preguiçosa ou tamanho do payload
• Busca de dados de página ou componente com useFetch, useAsyncData ou $fetch
• Problemas de roteamento Nuxt relacionados a parâmetros de rota, middleware ou diferenças entre SSR/cliente

Segurança de Hidratação

• Mantenha a primeira renderização determinística. Não coloque Date.now(), Math.random(), APIs somente para navegador ou leituras de armazenamento diretamente no estado do template renderizado por SSR.
• Mova a lógica somente para navegador para dentro de onMounted(), import.meta.client, ClientOnly ou um componente .client.vue quando o servidor não puder produzir a mesma marcação.
• Use o composable useRoute() do Nuxt, não o do vue-router.
• Não use route.fullPath para conduzir a marcação renderizada por SSR. Fragmentos de URL são somente para cliente, o que pode criar incompatibilidades de hidratação.
• Trate ssr: false como uma escotilha de escape para áreas verdadeiramente somente para navegador, não uma correção padrão para incompatibilidades.

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 buscador não for uma simples chamada $fetch(), quando você precisar de uma chave personalizada ou quando estiver compondo múltiplas 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 SSR e hidratação.
• Use $fetch() para escritas acionadas pelo usuário ou ações somente para 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. Trate status === 'pending' na IU.
• Use server: false apenas para dados que não são necessários para SEO ou para a primeira pintura.
• 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 no 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 em tempo de build
• swr: servir conteúdo em cache e revalidar em segundo plano
• isr: regeneração estática incremental em plataformas suportadas
• ssr: false: rota renderizada no cliente
• cache ou redirect: comportamento de resposta em nível de 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 Desempenho

• O Nuxt já divide o código das páginas por rota. Mantenha os limites das rotas 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 IU realmente precise dele.
• Use hidratação preguiçosa para IU interativa abaixo da dobra 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 inatividade.
• A hidratação preguiçosa do Nuxt funciona em componentes de arquivo único. 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.

Checklist de Revisão

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