Claude Code Nuxt: Nuxt 3, Server-Side Rendering und Full-Stack Vue mit KI

Nuxt 3 ist eines der komplexesten Full-Stack-Frameworks im JavaScript-Ökosystem — und gleichzeitig eines der mächtigsten. File-based Routing, Auto-Imports, Server Routes, mehrere Rendering-Modi, Nitro als universeller Server: wer Nuxt wirklich versteht, baut damit schnell produktionsreife Anwendungen. Wer es nicht versteht, kämpft mit magischen Importen, hydration mismatches und einer Ordnerstruktur, die mehr tut als sie aussieht.

Claude Code Nuxt-Entwicklung hebt diese Kurve an: nicht durch Erklären von Dokumentation, sondern durch konkretes Mitarbeiten im Projekt. Claude Code liest deine nuxt.config.ts, versteht deine Verzeichnisstruktur, kennt den Unterschied zwischen server/api/ und composables/ und hilft dir, Nuxt-typische Probleme zu lösen, bevor sie entstehen. Dieser Artikel zeigt, wie das in der Praxis aussieht.

1. Nuxt 3 Projektstruktur verstehen

Nuxt lebt von Konventionen. Ein neues Projekt anlegen ist einfach:

npx nuxi@latest init mein-projekt
cd mein-projekt
npm install

Was dabei entsteht, ist mehr als ein Ordner mit Dateien. Nuxt liest die Verzeichnisstruktur und konfiguriert sich selbst daraus. Die wichtigsten Konventionen:

mein-projekt/
├── pages/           # File-based Routing
├── components/      # Auto-importierte Komponenten
├── composables/     # Auto-importierte Composables
├── server/
│   ├── api/         # Server-Side API Routes
│   └── middleware/  # Server Middleware
├── layouts/         # Seitenlayouts
├── plugins/         # Nuxt Plugins
├── middleware/      # Client-Side Route Middleware
├── public/          # Statische Assets
└── nuxt.config.ts   # Konfiguration

Claude Code erkennt diese Struktur vollständig. Wenn du fragst "Wie füge ich eine neue API Route hinzu?", antwortet Claude Code nicht mit allgemeiner Theorie — es liest deine server/api/-Ordner, schaut wie deine bestehenden Routes aufgebaut sind, und schlägt eine neue Route vor, die exakt zu deinem Stil passt.

2. File-based Routing: Seiten ohne Konfiguration

Nuxt erzeugt Routen automatisch aus dem pages/-Verzeichnis. Keine router.ts, keine manuelle Route-Definition. Jede Datei wird eine Route:

pages/
├── index.vue          # /
├── about.vue          # /about
├── blog/
│   ├── index.vue      # /blog
│   └── [slug].vue     # /blog/:slug (dynamische Route)
└── user/
    └── [id]/
        ├── index.vue  # /user/:id
        └── settings.vue # /user/:id/settings

Claude Code hilft hier auf zwei Ebenen: beim Anlegen neuer Seiten mit der richtigen Struktur, und beim Debugging wenn Routen nicht wie erwartet funktionieren. Ein typischer Prompt:

claude "Ich möchte eine Route /produkte/:kategorie/:id
erstellen. Welche Dateistruktur brauche ich und wie greife
ich auf kategorie und id in der Komponente zu?"

Claude Code liest deinen pages/-Ordner, erklärt die korrekte Dateistruktur und zeigt direkt, wie du mit useRoute() auf die Parameter zugreifst — inklusive TypeScript-Typisierung wenn du TypeScript verwendest.

Nested Routes und Layouts

Nuxt unterstützt verschachtelte Layouts für komplexe Seitenstrukturen. Claude Code kennt das Konzept und kann dir helfen, ein konsistentes Layout-System aufzubauen:

<!-- layouts/default.vue -->
<template>
  <div>
    <AppHeader />
    <main>
      <slot />
    </main>
    <AppFooter />
  </div>
</template>

<!-- pages/dashboard.vue -->
<script setup>
definePageMeta({
  layout: 'dashboard'
})
</script>

3. Auto-Imports: Magie mit Konsequenzen

Eines der polarisierendsten Nuxt-Features: Auto-Imports. Kein import { ref } from 'vue', kein import { useRouter } from '#app' — Nuxt importiert alles automatisch, was in bestimmten Verzeichnissen liegt oder aus Vue und Nuxt stammt.

Das spart Code. Es verursacht aber auch Verwirrung, wenn man nicht weiß, woher ein Symbol kommt:

<!-- Das funktioniert in Nuxt ohne jeden Import -->
<script setup lang="ts">
const route = useRoute()
const router = useRouter()
const count = ref(0)
const doubled = computed(() => count.value * 2)

// Eigene Composables aus composables/ auch automatisch verfügbar
const { data, status } = useUserData()
</script>

Claude Code navigiert diesen Bereich zuverlässig. Wenn du fragst "Warum ist mein Composable nicht verfügbar?", liest Claude Code die Datei, prüft ob sie im richtigen Verzeichnis liegt, prüft die Benennung (Nuxt erwartet useXxx-Konvention für Auto-Import) und erklärt genau was fehlt.

4. Server Routes und API-Endpunkte

Nuxt ist ein Full-Stack-Framework. server/api/ ist der Ort für Server-Side Logik — Datenbankzugriffe, externe API-Calls, alles was nicht im Browser laufen soll oder darf.

// server/api/produkte/index.get.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event)
  const { kategorie, limit = 20 } = query

  // Datenbankabfrage (läuft nur auf dem Server)
  const produkte = await db.produkt.findMany({
    where: kategorie ? { kategorie: String(kategorie) } : undefined,
    take: Number(limit),
    orderBy: { createdAt: 'desc' }
  })

  return produkte
})

Die Dateinamens-Konvention entscheidet über die HTTP-Methode: index.get.ts für GET, index.post.ts für POST, index.ts für alle Methoden. Claude Code kennt diese Konventionen und hält sie automatisch ein.

// server/api/produkte/index.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)

  // Validierung
  if (!body.name || !body.preis) {
    throw createError({
      statusCode: 400,
      message: 'name und preis sind Pflichtfelder'
    })
  }

  const produkt = await db.produkt.create({
    data: {
      name: body.name,
      preis: Number(body.preis),
      beschreibung: body.beschreibung ?? ''
    }
  })

  return produkt
})

Claude Code ergänzt hier automatisch: Fehlerbehandlung mit createError, Input-Validierung, konsistente Rückgabetypen. Frag konkret:

claude "Erstelle eine POST Route unter server/api/bestellungen
die eine Bestellung anlegt. Validiere dass produkt_id und menge
vorhanden sind. Nutze Prisma für den DB-Zugriff."

5. useFetch und useAsyncData: Daten im richtigen Modus

Datenabruf in Nuxt ist kontextabhängig: ob der Request beim ersten Seitenaufruf (SSR), beim Client-Navigation oder gar nicht auf dem Server stattfinden soll, hängt von der Komponente und den Composables ab.

useFetch ist der Standardweg für die meisten Fälle:

<script setup lang="ts">
// Ruft beim SSR auf dem Server ab, gibt Daten an Client weiter
// Beim Client-Navigation: erneuter Fetch im Browser
const { data: produkte, status, error, refresh } = await useFetch('/api/produkte', {
  query: { kategorie: 'elektronik', limit: 10 }
})
</script>

<template>
  <div v-if="status === 'pending'">Lädt...</div>
  <div v-else-if="error">Fehler: {{ error.message }}</div>
  <ul v-else>
    <li v-for="produkt in produkte" :key="produkt.id">
      {{ produkt.name }} — {{ produkt.preis }} €
    </li>
  </ul>
</template>

useAsyncData bietet mehr Kontrolle, wenn du keinen direkten Nuxt-API-Endpunkt hast:

<script setup lang="ts">
const { data: benutzer } = await useAsyncData('benutzer', async () => {
  // Direkter DB-Zugriff oder externer API-Call
  return $fetch('/api/benutzer/profil')
})
</script>

Der Schlüssel-Parameter ('benutzer') ist wichtig: er verhindert doppelte Fetches wenn dieselben Daten an mehreren Stellen abgerufen werden. Claude Code erklärt dieses Konzept und hilft dir, den richtigen Key zu wählen — und warnt dich, wenn du denselben Key versehentlich zweimal verwendest.

6. Nuxt Modules: Das Ökosystem nutzen

Nuxt Modules erweitern das Framework ohne manuellen Konfigurationsaufwand. Die wichtigsten:

• @nuxt/ui — Komponenten-Bibliothek auf Basis von Tailwind
• @nuxtjs/tailwindcss — Tailwind CSS Integration
• @pinia/nuxt — State Management mit Pinia
• @nuxt/image — Automatische Bildoptimierung
• @nuxtjs/i18n — Internationalisierung
• @sidebase/nuxt-auth — Authentication

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/ui',
    '@pinia/nuxt',
    '@nuxt/image',
  ],
  ui: {
    global: true
  }
})

Claude Code kennt die gängigen Nuxt Modules und deren Konfigurationsoptionen. Wenn du ein Modul hinzufügst und nicht weißt wie es konfiguriert wird:

claude "Ich habe @nuxtjs/i18n installiert. Konfiguriere es
für Deutsch und Englisch, mit /de und /en als Prefix-Strategie.
Zeige auch wie ich useI18n in Komponenten verwende."

7. SSR, SSG und SPA: Den richtigen Modus wählen

Nuxt unterstützt drei grundlegende Rendering-Modi, die du pro Seite unterschiedlich setzen kannst:

• SSR (Server-Side Rendering) — Standard. HTML wird auf dem Server generiert, JavaScript im Browser hydratisiert. Gut für SEO und First Load Performance.
• SSG (Static Site Generation) — HTML wird beim Build generiert. Perfekt für Content-Seiten die sich selten ändern.
• SPA (Single Page Application) — Kein Server-Rendering. Gut für Dashboards und geschützte Bereiche.

// nuxt.config.ts
export default defineNuxtConfig({
  // Globaler Modus
  ssr: true,

  routeRules: {
    // Bestimmte Routen statisch generieren
    '/blog/**': { prerender: true },
    // Dashboard ohne SSR
    '/dashboard/**': { ssr: false },
    // API-Antworten cachen
    '/api/produkte': { cache: { maxAge: 60 * 5 } }
  }
})

Claude Code hilft dir, den richtigen Modus zu wählen und erklärt die Performance-Konsequenzen. Ein häufiger Fehler: SSR-Seiten die auf Browser-APIs zugreifen (window, document) und damit beim Server-Rendering crashen. Claude Code erkennt dieses Muster und zeigt die korrekte Lösung:

// Falsch: schlägt beim SSR fehl
const breite = window.innerWidth

// Richtig: nur im Client ausführen
const breite = ref(0)
onMounted(() => {
  breite.value = window.innerWidth
})

8. Nitro: Der universelle Server unter der Haube

Nuxt 3 nutzt Nitro als Server-Engine. Nitro kompiliert deine Anwendung für verschiedene Deployment-Ziele ohne Code-Änderungen:

# Node.js Server (Standard)
nuxt build

# Static (Vercel, Netlify, GitHub Pages)
nuxt generate

# Cloudflare Workers
NITRO_PRESET=cloudflare nuxt build

# Vercel Edge Functions
NITRO_PRESET=vercel-edge nuxt build

# AWS Lambda
NITRO_PRESET=aws-lambda nuxt build

Claude Code kennt alle Nitro-Presets und deren Einschränkungen. Wenn du auf Cloudflare Workers deployen willst, weiß Claude Code zum Beispiel, dass Node.js-spezifische APIs dort nicht funktionieren und zeigt dir die Alternativen.

Deployment mit Vercel

Das einfachste Deployment für Nuxt 3:

# Vercel CLI installieren
npm i -g vercel

# Aus dem Projekt-Root
vercel

# Nuxt erkennt Vercel automatisch — kein Preset nötig

Für selbst gehostete Deployments:

nuxt build
# Output liegt in .output/
node .output/server/index.mjs

9. Wie Claude Code im Nuxt-Alltag konkret hilft

Nach mehreren Monaten Nuxt-Entwicklung mit Claude Code haben sich einige Muster herauskristallisiert, wo die Zusammenarbeit besonders effektiv ist:

Hydration Mismatches debuggen: Der berüchtigtste Nuxt-Fehler — HTML auf Server und Client stimmt nicht überein. Claude Code liest die Komponente, findet den Unterschied (oft ein Datum, eine Zufallszahl oder eine Browser-API) und zeigt den Fix.

claude "Ich bekomme einen Hydration Mismatch Fehler in dieser
Komponente. Finde die Ursache:" < components/ProduktKarte.vue

Pinia Stores mit SSR-Kompatibilität: State Management in SSR-Kontext hat Tücken. Claude Code schreibt Pinia Stores die korrekt mit Nuxt funktionieren:

// stores/warenkorb.ts
export const useWarenkorbStore = defineStore('warenkorb', () => {
  const items = ref<WarenkorbItem[]>([])

  const gesamtpreis = computed(() =>
    items.value.reduce((sum, item) => sum + item.preis * item.menge, 0)
  )

  function hinzufuegen(produkt: Produkt, menge = 1) {
    const existierend = items.value.find(i => i.id === produkt.id)
    if (existierend) {
      existierend.menge += menge
    } else {
      items.value.push({ ...produkt, menge })
    }
  }

  return { items, gesamtpreis, hinzufuegen }
})

Middleware für Authentifizierung: Route Guards in Nuxt laufen sowohl auf dem Server als auch im Client. Claude Code schreibt Middleware die in beiden Kontexten korrekt funktioniert:

// middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const { loggedIn } = useAuth()

  if (!loggedIn.value) {
    return navigateTo('/login?redirect=' + to.path)
  }
})

Zwei verwandte Artikel die auf diesem Thema aufbauen:

• Claude Code Debugging — Bugs in Nuxt-Projekten systematisch finden und beheben
• Claude Code für Unternehmen — Deployment, Zugriffskontrolle und Team-Workflows auf Unternehmensebene

Nuxt 3 ist mächtig — aber seine Magie hat Voraussetzungen. Wer die Konventionen kennt, baut schnell. Wer sie nicht kennt, kämpft gegen das Framework. Claude Code überbrückt diese Lücke: es liest deinen Code, kennt die Nuxt-Konventionen und hilft dir, in dem Framework zu denken statt gegen es. Für neue Nuxt-Projekte, für die Migration von Nuxt 2 auf Nuxt 3, für das Debugging von SSR-Problemen — in all diesen Situationen ist Claude Code ein produktiver Partner, nicht nur ein Nachschlagewerk.

Wer tiefer einsteigen will — in Agents, MCP-Server, Hooks und Multi-Agent-Workflows — findet den Weg dorthin im Claude Code Kurs.