nuxt4-patterns

Modèles Nuxt 4

À utiliser lors de la construction 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 serveur et l'état client
• Décisions de rendu au niveau des routes comme le pré-rendu, SWR, ISR ou les sections exclusivement client
• Travail sur les performances autour du chargement différé, de l'hydratation paresseuse ou de la taille des payloads
• 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 exclusives au navigateur ou les lectures de stockage directement dans l'état du template rendu par SSR.
• Déplacez la logique exclusive 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 composable useRoute() de Nuxt, pas celle de vue-router.
• N'utilisez pas route.fullPath pour générer le balisage rendu par SSR. Les fragments d'URL sont exclusifs au client, ce qui peut créer des incohérences d'hydratation.
• Considérez ssr: false comme une échappatoire pour les zones vraiment exclusives 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 le payload 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 exclusives au client, pas 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 à la première peinture.
• Réduisez la taille du payload avec pick et préférez des payloads moins profonds lorsque la réactivité profonde est inutile.

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 en cache et le revalider en arrière-plan
• isr : régénération statique incrémentielle sur les plateformes 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, pas 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 de route significatives avant de micro-optimiser les divisions de composants.
• Utilisez le préfixe Lazy pour importer dynamiquement les composants non critiques.
• Rendez conditionnellement les composants différés avec v-if afin que le morceau ne soit chargé que lorsque l'interface utilisateur en a réellement besoin.
• Utilisez l'hydratation paresseuse pour les éléments interactifs non critiques situés en dessous de la ligne de flottaison.

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

• Pour des stratégies personnalisées, utilisez defineLazyHydrationComponent() avec une stratégie de visibilité ou d'inactivité.
• L'hydratation paresseuse de Nuxt fonctionne sur les composants à fichier unique. Passer 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 payloads générés.

Liste de vérification

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