nuxt4-patterns

Nuxt 4 Patterns

Verwenden Sie dies beim Erstellen oder Debuggen von Nuxt 4 Apps mit SSR, Hybrid-Rendering, Routenregeln oder page-level Datenabruf.

Wann aktivieren

• Hydrationskonflikte zwischen Server-HTML und Client-Zustand
• Rendering-Entscheidungen auf Routenebene wie Prerender, SWR, ISR oder Client-only-Abschnitte
• Performance-Arbeiten rund um Lazy Loading, Lazy Hydration oder Payload-Größe
• Datenabruf auf Seiten- oder Komponentenebene mit useFetch, useAsyncData oder $fetch
• Nuxt Routing-Probleme im Zusammenhang mit Routenparametern, Middleware oder SSR/Client-Unterschieden

Hydrationssicherheit

• Halten Sie das erste Rendern deterministisch. Verwenden Sie Date.now(), Math.random(), Browser-only-APIs oder Storage-Reads nicht direkt im SSR-gerenderten Template-Zustand.
• Verschieben Sie Browser-only-Logik hinter onMounted(), import.meta.client, ClientOnly oder eine .client.vue-Komponente, wenn der Server nicht das gleiche Markup erzeugen kann.
• Verwenden Sie die useRoute()-Composable von Nuxt, nicht die von vue-router.
• Verwenden Sie route.fullPath nicht, um SSR-gerendertes Markup zu steuern. URL-Fragmente sind Client-only und können Hydrationskonflikte erzeugen.
• Behandeln Sie ssr: false als Notlösung für wirklich Browser-only-Bereiche, nicht als Standardlösung für Konflikte.

Datenabruf

• Bevorzugen Sie await useFetch() für SSR-sichere API-Reads in Seiten und Komponenten. Es leitet serverabgerufene Daten in das Nuxt-Payload und vermeidet einen zweiten Fetch bei der Hydration.
• Verwenden Sie useAsyncData(), wenn der Fetcher kein einfacher $fetch()-Aufruf ist, wenn Sie einen benutzerdefinierten Schlüssel benötigen oder wenn Sie mehrere asynchrone Quellen kombinieren.
• Geben Sie useAsyncData() einen stabilen Schlüssel für Cache-Wiederverwendung und vorhersagbares Refresh-Verhalten.
• Halten Sie useAsyncData()-Handler nebenwirkungsfrei. Sie können während SSR und Hydration ausgeführt werden.
• Verwenden Sie $fetch() für benutzerausgelöste Schreibvorgänge oder Client-only-Aktionen, nicht für page-level-Daten, die von SSR hydriert werden sollen.
• Verwenden Sie lazy: true, useLazyFetch() oder useLazyAsyncData() für nicht-kritische Daten, die die Navigation nicht blockieren sollten. Behandeln Sie status === 'pending' in der UI.
• Verwenden Sie server: false nur für Daten, die nicht für SEO oder den ersten Paint benötigt werden.
• Reduzieren Sie die Payload-Größe mit pick und bevorzugen Sie flachere Payloads, wenn keine tiefe Reaktivität erforderlich ist.

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

Routenregeln

Bevorzugen Sie routeRules in nuxt.config.ts für Rendering- und Caching-Strategie:

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

• prerender: statisches HTML zur Build-Zeit
• swr: gecachten Inhalt ausliefern und im Hintergrund neu validieren
• isr: inkrementelle statische Regeneration auf unterstützten Plattformen
• ssr: false: client-gerenderte Route
• cache oder redirect: Nitro-Level-Antwortverhalten

Wählen Sie Routenregeln pro Routengruppe, nicht global. Marketingseiten, Kataloge, Dashboards und APIs benötigen normalerweise unterschiedliche Strategien.

Lazy Loading und Performance

• Nuxt teilt Seiten bereits automatisch pro Route auf. Halten Sie Routengrenzen sinnvoll, bevor Sie mit Mikrooptimierungen von Komponententrennung beginnen.
• Verwenden Sie das Lazy-Präfix, um nicht-kritische Komponenten dynamisch zu importieren.
• Rendern Sie Lazy-Komponenten bedingt mit v-if, damit der Chunk erst geladen wird, wenn die UI ihn tatsächlich benötigt.
• Verwenden Sie Lazy Hydration für unter dem Falz liegende oder nicht-kritische interaktive UI.

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

• Verwenden Sie für benutzerdefinierte Strategien defineLazyHydrationComponent() mit einer Sichtbarkeits- oder Leerlaufstrategie.
• Nuxt Lazy Hydration funktioniert mit Single-File-Komponenten. Das Übergeben neuer Props an eine lazy hydrierte Komponente löst sofort die Hydration aus.
• Verwenden Sie NuxtLink für die interne Navigation, damit Nuxt Routenkomponenten und generierte Payloads vorab laden kann.

Review-Checkliste

• Erstes SSR-Rendering und hydriertes Client-Rendering erzeugen das gleiche Markup
• Seitendaten verwenden useFetch oder useAsyncData, nicht top-level $fetch
• Nicht-kritische Daten sind lazy und haben eine explizite Lade-UI
• Routenregeln entsprechen den SEO- und Aktualitätsanforderungen der Seite
• Schwere interaktive Inseln werden lazy-geladen oder lazy-hydriert