nuxt4-patterns

Modèles Nuxt 4

À utiliser lors de la création ou du débogage d'applications Nuxt 4 avec SSR, rendu hybride, règles de routage ou récupération de données au niveau des pages.

Quand activer

• Incohérences d'hydratation entre le HTML du serveur et l'état client
• Décisions de rendu au niveau des routes (prerender, SWR, ISR, ou sections client uniquement)
• Travail sur les performances lié au chargement différé, à l'hydratation paresseuse ou à la taille des charges utiles
• Récupération de données de page ou de composant avec useFetch, useAsyncData ou $fetch
• Problèmes de routage Nuxt liés aux paramètres de route, au middleware ou aux différences SSR/client

Sécurité d'hydratation

• Gardez le premier rendu déterministe. N'utilisez pas Date.now(), Math.random(), les API propres au navigateur ou les lectures de stockage directement dans l'état du template rendu par SSR.
• Déplacez la logique propre au navigateur derrière onMounted(), import.meta.client, ClientOnly ou un composant .client.vue lorsque le serveur ne peut pas produire le même balisage.
• Utilisez la fonction composable useRoute() de Nuxt, et non celle de vue-router.
• N'utilisez pas route.fullPath pour piloter le balisage rendu par SSR. Les fragments d'URL sont propres au client, ce qui peut créer des incohérences d'hydratation.
• Considérez ssr: false comme une porte de sortie pour les zones vraiment réservées au navigateur, et non comme un correctif par défaut pour les incohérences.

Récupération de données

• Préférez await useFetch() pour les lectures d'API compatibles SSR dans les pages et les composants. Il transmet les données récupérées par le serveur dans la charge utile Nuxt et évite une seconde récupération lors de l'hydratation.
• Utilisez useAsyncData() lorsque le récupérateur n'est pas un simple appel $fetch(), lorsque vous avez besoin d'une clé personnalisée ou lorsque vous composez plusieurs sources asynchrones.
• Donnez à useAsyncData() une clé stable pour la réutilisation du cache et un comportement de rafraîchissement prévisible.
• Gardez les gestionnaires de useAsyncData() sans effets secondaires. Ils peuvent s'exécuter pendant le SSR et l'hydratation.
• Utilisez $fetch() pour les écritures déclenchées par l'utilisateur ou les actions propres au client, et non pour les données de page de premier niveau qui doivent être hydratées à partir du SSR.
• Utilisez lazy: true, useLazyFetch() ou useLazyAsyncData() pour les données non critiques qui ne doivent pas bloquer la navigation. Gérez status === 'pending' dans l'interface utilisateur.
• Utilisez server: false uniquement pour les données qui ne sont pas nécessaires au SEO ou au premier affichage.
• Réduisez la taille de la charge utile avec pick et privilégiez les charges utiles moins profondes lorsque la réactivité profonde n'est pas nécessaire.

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

Règles de routage

Préférez routeRules dans nuxt.config.ts pour la stratégie de rendu et de mise en cache :

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

• prerender : HTML statique au moment de la construction
• swr : servir le contenu mis en cache et le revalider en arrière-plan
• isr : régénération statique incrémentielle sur les plates-formes prises en charge
• ssr: false : route rendue côté client
• cache ou redirect : comportement de réponse au niveau de Nitro

Choisissez les règles de routage par groupe de routes, et non globalement. Les pages marketing, les catalogues, les tableaux de bord et les API nécessitent généralement des stratégies différentes.

Chargement différé et performances

• Nuxt divise déjà le code des pages par route. Gardez les limites des routes significatives avant de micro-optimiser les divisions des composants.
• Utilisez le préfixe Lazy pour importer dynamiquement les composants non critiques.
• Affichez conditionnellement les composants différés avec v-if afin que le bloc ne soit pas chargé tant que l'interface utilisateur n'en a pas réellement besoin.
• Utilisez l'hydratation paresseuse pour les interfaces utilisateur interactives situées en dessous de la ligne de flottaison ou non critiques.

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

• Pour les stratégies personnalisées, utilisez defineLazyHydrationComponent() avec une stratégie de visibilité ou d'inactivité.
• L'hydratation paresseuse de Nuxt fonctionne sur les composants monofichiers. Le passage de nouvelles props à un composant hydraté paresseusement déclenchera l'hydratation immédiatement.
• Utilisez NuxtLink pour la navigation interne afin que Nuxt puisse précharger les composants de route et les charges utiles générées.

Liste de vérification pour la révision

• Le premier rendu SSR et le rendu client hydraté produisent le même balisage
• Les données de la page utilisent useFetch ou useAsyncData, et non $fetch au niveau supérieur
• Les données non critiques sont différées et disposent d'une interface utilisateur de chargement explicite
• Les règles de routage correspondent aux exigences de SEO et de fraîcheur de la page
• Les îles interactives lourdes sont chargées ou hydratées paresseusement