patrones-nuxt4

Patrones de Nuxt 4

Úselo 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 para cliente
• Trabajo de rendimiento en torno a carga diferida, hidratación diferida o tamaño de carga útil
• 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, middlewares o diferencias entre SSR y cliente

Seguridad de hidratación

• Mantenga el primer renderizado determinista. No coloque Date.now(), Math.random(), APIs solo de navegador ni lecturas de almacenamiento directamente en el estado de la plantilla renderizada por SSR.
• Mueva la lógica solo de navegador detrás de onMounted(), import.meta.client, ClientOnly o un componente .client.vue cuando el servidor no pueda producir el mismo marcado.
• Use el composable useRoute() de Nuxt, no el de vue-router.
• No use 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.
• Trate ssr: false como una vía de escape para áreas verdaderamente solo de navegador, no como una solución predeterminada para desajustes.

Obtención de datos

• Prefiera await useFetch() para lecturas de API seguras para SSR en páginas y componentes. Reenvía los datos obtenidos por el servidor a la carga útil de Nuxt y evita una segunda obtención en la hidratación.
• Use useAsyncData() cuando el recuperador no sea una simple llamada a $fetch(), cuando necesite una clave personalizada o cuando esté componiendo múltiples fuentes asíncronas.
• Asigne a useAsyncData() una clave estable para reutilización de caché y comportamiento de actualización predecible.
• Mantenga los manejadores de useAsyncData() libres de efectos secundarios. Pueden ejecutarse durante SSR e hidratación.
• Use $fetch() para escrituras desencadenadas por el usuario o acciones solo de cliente, no para datos de página de nivel superior que deban hidratarse desde SSR.
• Use lazy: true, useLazyFetch() o useLazyAsyncData() para datos no críticos que no deban bloquear la navegación. Maneje status === 'pending' en la interfaz de usuario.
• Use server: false solo para datos que no sean necesarios para SEO o la primera pintura.
• Reduzca el tamaño de la carga útil con pick y prefiera cargas útiles menos profundas cuando la reactividad profunda no sea necesaria.

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

Prefiera 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 en el cliente
• cache o redirect: comportamiento de respuesta a nivel de Nitro

Elija reglas de ruta por grupo de rutas, no de forma global. Las páginas de marketing, catálogos, paneles de control y API generalmente necesitan estrategias diferentes.

Carga diferida y rendimiento

• Nuxt ya divide el código de las páginas por ruta. Mantenga los límites de ruta significativos antes de micro-optimizar divisiones de componentes.
• Use el prefijo Lazy para importar dinámicamente componentes no críticos.
• Renderice componentes diferidos condicionalmente con v-if para que el fragmento no se cargue hasta que la interfaz de usuario realmente lo necesite.
• Use hidratación diferida para elementos interactivos no visibles inicialmente o no críticos.

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

• Para estrategias personalizadas, use defineLazyHydrationComponent() con una estrategia de visibilidad o inactividad.
• La hidratación diferida de Nuxt funciona en componentes de un solo archivo. Pasar nuevas props a un componente con hidratación diferida activará la hidratación inmediatamente.
• Use NuxtLink para la navegación interna para que Nuxt pueda precargar los componentes de la ruta y las cargas útiles generadas.

Lista de verificación de revisión

• El primer renderizado SSR y el renderizado hidratado del cliente 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 actualización de la página
• Las islas interactivas pesadas se cargan de forma diferida o se hidratan de forma diferida