Patrones Nuxt 4

¿Qué hace Patrones Nuxt 4?

Úsalo al construir o depurar aplicaciones Nuxt 4 con SSR, renderizado híbrido, reglas de ruta u obtención de datos a nivel de página.

Cuándo activarlo

• Desajustes de hidratación entre el HTML del servidor y el estado del cliente
• Decisiones de renderizado a nivel de ruta como prerender, SWR, ISR o secciones solo cliente
• Trabajo de rendimiento en torno a carga diferida, hidratación perezosa o tamaño de payload
• Obtención de datos de página o componente con useFetch, useAsyncData o $fetch
• Problemas de enrutamiento de Nuxt relacionados con parámetros de ruta, middleware o diferencias SSR/cliente

Seguridad en hidratación

• Mantén la primera renderización determinista. No pongas Date.now(), Math.random(), APIs solo del navegador ni lecturas de almacenamiento directamente en el estado de plantilla renderizado por SSR.
• Mueve la lógica solo del navegador detrás de onMounted(), import.meta.client, ClientOnly o un componente .client.vue cuando el servidor no pueda producir el mismo marcado.
• Usa el composable useRoute() de Nuxt, no el de vue-router.
• No uses route.fullPath para impulsar el marcado renderizado por SSR. Los fragmentos de URL son solo de cliente, lo que puede crear desajustes de hidratación.
• Trata ssr: false como una vía de escape para áreas verdaderamente solo del navegador, no como una corrección predeterminada para desajustes.

Obtención de datos

• Prefiere await useFetch() para lecturas de API seguras para SSR en páginas y componentes. Reenvía los datos obtenidos en el servidor al payload de Nuxt y evita una segunda obtención en la hidratación.
• Usa useAsyncData() cuando el obtenedor no sea una simple llamada $fetch(), cuando necesites una clave personalizada o cuando estés componiendo múltiples fuentes asíncronas.
• Dale a useAsyncData() una clave estable para la reutilización de caché y un comportamiento de actualización predecible.
• Mantén los manejadores de useAsyncData() libres de efectos secundarios. Pueden ejecutarse durante SSR e hidratación.
• Usa $fetch() para escrituras activadas por el usuario o acciones solo del cliente, no para datos de página de nivel superior que deban hidratarse desde SSR.
• Usa lazy: true, useLazyFetch() o useLazyAsyncData() para datos no críticos que no deban bloquear la navegación. Maneja status === 'pending' en la interfaz de usuario.
• Usa server: false solo para datos que no sean necesarios para SEO o la primera pintura.
• Reduce el tamaño del payload con pick y prefiere payloads más superficiales cuando la reactividad profunda sea innecesaria.

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,
})

Reglas de ruta

Prefiere routeRules en nuxt.config.ts para la estrategia de renderizado y caché:

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

• prerender: HTML estático en tiempo de compilación
• swr: sirve contenido en caché y revalida en segundo plano
• isr: regeneración estática incremental en plataformas compatibles
• ssr: false: ruta renderizada solo en cliente
• cache o redirect: comportamiento de respuesta a nivel de Nitro

Elige reglas de ruta por grupo de rutas, no globalmente. Las páginas de marketing, catálogos, paneles de control y APIs generalmente necesitan estrategias diferentes.

Carga diferida y rendimiento

• Nuxt ya divide el código de las páginas por ruta. Mantén los límites de ruta significativos antes de micro-optimizar divisiones de componentes.
• Usa el prefijo Lazy para importar dinámicamente componentes no críticos.
• Renderiza condicionalmente componentes diferidos con v-if para que el chunk no se cargue hasta que la interfaz realmente lo necesite.
• Usa hidratación perezosa para contenido no visible en pantalla o interfaz interactiva no crítica.

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

• Para estrategias personalizadas, usa defineLazyHydrationComponent() con una estrategia de visibilidad o inactividad.
• La hidratación perezosa de Nuxt funciona en componentes de un solo archivo. Pasar nuevas props a un componente hidratado perezosamente activará la hidratación de inmediato.
• Usa NuxtLink para la navegación interna para que Nuxt pueda precargar los componentes de ruta y los payloads generados.

Lista de verificación de revisión

• La primera renderización SSR y la renderización del cliente hidratada producen el mismo marcado
• Los datos de página usan useFetch o useAsyncData, no $fetch de nivel superior
• Los datos no críticos son diferidos y tienen una interfaz de usuario de carga explícita
• Las reglas de ruta coinciden con los requisitos de SEO y frescura de la página
• Las islas interactivas pesadas se cargan de forma diferida o se hidratan perezosamente