Nuxt 4 Patterns

Was macht Nuxt 4 Patterns?

Verwenden Sie diese Anleitung beim Erstellen oder Debuggen von Nuxt 4 Apps mit SSR, Hybrid-Rendering, Route-Regeln oder Page-Level-Datenabruf.

Wann aktivieren

• Hydrationskonflikte zwischen Server-HTML und Client-Zustand
• Route-Level-Rendering-Entscheidungen wie Prerender, SWR, ISR oder Client-Only-Bereiche
• Performance-Arbeiten rund um Lazy Loading, Lazy Hydration oder Payload-Größe
• Page- oder Component-Datenabruf mit useFetch, useAsyncData oder $fetch
• Nuxt Routing-Probleme im Zusammenhang mit Routenparametern, Middleware oder SSR/Client-Unterschieden

Hydration-Sicherheit

• Halten Sie den ersten Render deterministisch. Platzieren Sie Date.now(), Math.random(), Browser-Only-APIs oder Storage-Lesevorgänge nicht direkt in den SSR-gerenderten Template-Status.
• Verlagern 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 das Nuxt-eigene useRoute() Composable, nicht das aus vue-router.
• Verwenden Sie nicht route.fullPath, um SSR-gerendertes Markup zu steuern. URL-Fragmente sind Client-Only und können Hydrationskonflikte erzeugen.
• Behandeln Sie ssr: false als Notausstieg für wirklich Browser-Only-Bereiche, nicht als Standardlösung für Konflikte.

Datenabruf

• Bevorzugen Sie await useFetch() für SSR-sichere API-Aufrufe in Pages und Komponenten. Es leitet serverseitig abgerufene Daten in das Nuxt-Payload weiter und vermeidet einen zweiten Fetch beim Hydratieren.
• 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 die Wiederverwendung des Caches und ein vorhersagbares Aktualisierungsverhalten.
• Halten Sie Handler von useAsyncData() frei von Seiteneffekten. Sie können während SSR und Hydration ausgeführt werden.
• Verwenden Sie $fetch() für benutzerinitiierte Schreibvorgänge oder Client-Only-Aktionen, nicht für Page-Daten auf oberster Ebene, die aus SSR hydriert werden sollen.
• Verwenden Sie lazy: true, useLazyFetch() oder useLazyAsyncData() für nicht-kritische Daten, die die Navigation nicht blockieren sollen. 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,
})

Route-Regeln

Bevorzugen Sie routeRules in nuxt.config.ts für Render- und Caching-Strategien:

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: bereitgestellter Cache-Inhalt und erneute Validierung im Hintergrund
• isr: inkrementelle statische Regeneration auf unterstützten Plattformen
• ssr: false: clientseitig gerenderte Route
• cache oder redirect: Nitro-Level-Antwortverhalten

Wählen Sie Route-Regeln pro Routengruppe, nicht global. Marketingseiten, Kataloge, Dashboards und APIs benötigen in der Regel unterschiedliche Strategien.

Lazy Loading und Performance

• Nuxt teilt Seiten bereits automatisch nach Routen auf. Halten Sie Routengrenzen sinnvoll, bevor Sie Mikrooptimierungen an Komponenten-Aufteilungen vornehmen.
• Verwenden Sie das Lazy-Präfix, um nicht-kritische Komponenten dynamisch zu importieren.
• Rendern Sie Lazy-Komponenten bedingt mit v-if, sodass der Chunk erst geladen wird, wenn die UI ihn tatsächlich benötigt.
• Verwenden Sie Lazy Hydration für Under-the-fold- 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 Idle-Strategie.
• Nuxt Lazy Hydration arbeitet mit Einzeldatei-Komponenten. Das Übergeben neuer Props an eine lazy hydrierte Komponente löst sofort eine Hydration aus.
• Verwenden Sie NuxtLink für die interne Navigation, damit Nuxt Routenkomponenten und generierte Payloads vorab laden kann.

Review-Checkliste

• Der erste SSR-Render und der hydrierte Client-Render erzeugen das gleiche Markup
• Page-Daten verwenden useFetch oder useAsyncData, kein $fetch auf oberster Ebene
• Nicht-kritische Daten sind lazy und haben eine explizite Lade-UI
• Route-Regeln entsprechen den SEO- und Aktualitätsanforderungen der Seite
• Schwere interaktive Bereiche sind lazy-geladen oder lazy-hydriert