Vue-fejjel Nuxtba: mi változik

3.1Auto-import: mi jön magától, és mikor harap vissza

Nuxtban nem írsz importot a saját komponenseidhez, composable-jaidhoz, sem a Vue és a Nuxt API-jaihoz:

// Vue-projektben így írnád:
import { ref, computed, onMounted } from 'vue'
import UserCard from '~/components/UserCard.vue'
import { useCart } from '~/composables/useCart'

// Nuxtban egyik sem kell — mindhárom automatikusan elérhető.

Mi importálódik automatikusan, és mi nem:

A komponensek névtérbe kerülnek a mappaszerkezet szerint, ami elsőre meglepő:

app/components/UserCard.vue              →  <UserCard />
app/components/admin/UserCard.vue        →  <AdminUserCard />     ← nem <UserCard />!
app/components/admin/billing/Table.vue   →  <AdminBillingTable />

Ahol visszaharap

• Nem látod, honnan jön egy függvény. Ha egy ismeretlen useValami()-vel találkozol a kódban, nincs import, amit követhetnél. Két hely, ahol utánanézhetsz: a .nuxt/imports.d.ts (composable-ok és utilok) és a .nuxt/components.d.ts (komponensek). Az IDE „go to definition” általában működik, mert ezek valódi típusdeklarációk.
• Névütközés csendben eldől. Ha van egy app/utils/format.ts-ben formatDate-ed, és egy modul is exportál ilyet, az egyik nyer. Nincs hibaüzenet. Prefixálj (fmtDate) vagy importálj explicit módon.
• A barrel-fájl visszaüt. Ha csinálsz egy app/utils/index.ts-t, ami mindent re-exportál, azzal kilőtted a tree-shakinget: minden util bekerül a bundle-be, akkor is, ha egyet használsz. Workers-en, ahol méretlimit van, ez nem elméleti probléma (15. modul).

3.2useState vs. ref — a legdrágább hiba

Ez a szakasz ér a legtöbbet az egész modulban. Vue SPA-ban teljesen bevett minta a modul-szintű reaktív állapot:

// app/composables/useCart.ts
const items = ref<Item[]>([])          // ← modul-scope!

export const useCart = () => {
  return { items, add: (i: Item) => items.value.push(i) }
}

A böngészőben ez tökéletes: egy felhasználó, egy modulpéldány. A szerveren viszont a modul-scope nem kérésenkénti. A modul egyszer értékelődik ki, és az összes kérés ugyanazt a items tömböt látja. Az egyik felhasználó kosara megjelenik a másiknál — vagy ami rosszabb, az egyik tenant adata a másiknál.

// app/composables/useCart.ts
export const useCart = () => {
  // kérésenként izolált a szerveren, és átszerializálódik a kliensre
  const items = useState<Item[]>('cart', () => [])
  return { items, add: (i: Item) => items.value.push(i) }
}

A useState egy kulccsal azonosított, SSR-biztos állapot: a szerveren kérésenként külön példány, és az értéke bekerül a HTML payloadjába, hogy a kliens ugyanonnan folytassa. A szabály egyszerű:

3.3Composable-ok: hol hívhatók, és hol nem

A Nuxt-composable-ok (useRoute, useState, useFetch, useRuntimeConfig, …) egy rejtett kontextusból, a Nuxt-példányból dolgoznak. Ez a kontextus szinkron módon elérhető három helyen: komponens setup, plugin, és route middleware. Máshol nem.

<script setup>
const { data } = await useFetch('/api/me')

// await UTÁN, callbackben, vagy eseménykezelőben:
button.addEventListener('click', async () => {
  const cfg = useRuntimeConfig()   // „Nuxt instance unavailable"
})
</script>

<script setup>
// ① a legegyszerűbb: hívd a tetején, szinkronban, és zárd be a változóba
const cfg     = useRuntimeConfig()
const nuxtApp = useNuxtApp()
const { data } = await useFetch('/api/me')

async function onClick() {
  console.log(cfg.public.apiBase)        // már a kezünkben van

  // ② ha tényleg kontextus kell egy async ág mélyén:
  await nuxtApp.runWithContext(() => navigateTo('/projects'))
}
</script>

A gyakorlati szabály: minden use* hívás a <script setup> tetejére, szinkronban, az await-ek elé. Ha ezt megtartod, ezzel a hibaosztállyal nem találkozol.

Saját composable írása ugyanígy működik — csak arra figyelj, hogy ha Nuxt-composable-t hívsz benne, akkor a te composable-od is örökli a megkötést:

// app/composables/useTenant.ts
export const useTenant = () => {
  const route  = useRoute()                          // örökli a setup-megkötést
  const tenant = useState<Tenant | null>('tenant', () => null)
  const slug   = computed(() => route.params.tenant as string)
  return { tenant, slug }
}

3.4Compiler-makrók: definePageMeta és társai

Néhány Nuxt-függvény nem futásidejű hívás, hanem build-time makró — a fordító kiemeli a kódból, és a route-táblába fordítja. Ezért nem lehet nekik dinamikus értéket adni:

<script setup>
// ✓ így jó — statikus objektum
definePageMeta({
  layout: 'admin',
  middleware: ['auth', 'tenant'],
})

// ✗ így nem — a makró nem lát futásidejű változót
const l = user.isAdmin ? 'admin' : 'default'
definePageMeta({ layout: l })      // build-hiba vagy néma hiba

// ✓ ha futásidőben kell váltani:
setPageLayout(user.isAdmin ? 'admin' : 'default')
</script>

Ugyanez a logika érvényes a defineNuxtRouteMiddleware-re és a defineNuxtPlugin-re: a fájl helye és a makró együtt mondja meg a Nuxtnak, mit csináljon a kóddal.

3.5.client, .server és a feltételes futás

Négy eszközöd van arra, hogy valami csak az egyik oldalon fusson. Ezek nem cserélhetők fel:

<template>
  <ClientOnly>
    <RevenueChart :data="data" />
    <template #fallback>
      <!-- ez megy ki a HTML-be SSR-kor: nincs layout-ugrás, van mit indexelni -->
      <div class="chart-skeleton">Diagram betöltése…</div>
    </template>
  </ClientOnly>
</template>

3.6Hydration mismatch: a hét ok

Ez az a hibaosztály, ami SPA-ban nem létezik, és Nuxtban a leggyakoribb „miért csinálja ezt?” pillanat. A hiba mindig ugyanaz: a szerveren rendereltől eltérő HTML-t akar a kliens. A konzolban valami ilyet látsz: Hydration node mismatch vagy Hydration text content mismatch, és a komponens újrarenderelődik a kliensen (villan).

Hogyan szűkítsd le

1. Nézd meg a nyers HTML-t. curl vagy „forrás megtekintése” (nem a DevTools Elements fül, mert az már a hidratált DOM-ot mutatja). Ha ott már rossz, akkor SSR-hiba, nem hydration-hiba.
2. A konzolüzenet megmondja a csomópontot. Dev módban a Vue kiírja, melyik komponensben és milyen tartalomnál tér el.
3. Kapcsold ki felezéssel. Ha nagy az oldal, tedd <ClientOnly>-ba a gyanús felet — nem javításként, hanem hogy megtaláld a bűnöst.
4. Inkognitó, kiterjesztések nélkül. Ha ott nem jelentkezik, nem a te kódod a hibás.

3.7Idióma-váltó: amit másképp fogsz írni

Ezek nem hibák, csak más szokások. A bal oldali is működik általában — a jobb oldali az, ami Nuxtban helyes, és amit SSR mellett elvárnak tőled:

3.8Az első hét ellenőrzőlistája

Ha most kezdenél átírni valamit Nuxtra, ezt a hatot nézd át magadon:

• Van-e modul-szintű ref vagy megosztott mutálható objektum bárhol? → useState
• Minden use* hívás a setup tetején van, await előtt?
• Van-e window, document, localStorage hivatkozás védelem nélkül? → import.meta.client vagy onMounted
• Titok vagy DB-hozzáférés csak server/ alatt van? (2. modul táblája)
• A <ClientOnly>-k valódi okból vannak ott, nem hydration-hiba eltakarására?
• A meta-tagek useSeoMeta-val készülnek, nem onMounted-ben?

3.9Ellenőrizd magad