Nuxt for Devs · 22. modul

Referencia: a Nuxt-konvenciók térképe

Ez a modul nem olvasásra készült, hanem visszakeresésre. Egy helyen a könyvtárszerkezet, a fájlnév-konvenciók, az auto-import szabályai, a beépített composable-ök és komponensek, a szerveroldali segédfüggvények, a Cloudflare-releváns konfigurációs kulcsok és a parancsok. A végén a tanfolyam térképe: melyik modul melyik kérdésre válaszol.

22.1Könyvtárszerkezet (Nuxt 4)

projekt/
├─ app/                      ← a Vue-alkalmazás
│  ├─ assets/                build által feldolgozott eszközök
│  ├─ components/            auto-import, tetszőleges mélységig
│  ├─ composables/           auto-import — csak a legfelső szint
│  ├─ layouts/               <NuxtLayout> által használt sablonok
│  ├─ middleware/            útvonal-middleware (kliens + szerver)
│  ├─ pages/                 fájlrendszer-alapú útvonalak
│  ├─ plugins/               indulási kód, sorrend fájlnév szerint
│  ├─ utils/                 auto-import — csak a legfelső szint
│  ├─ app.vue                a gyökérkomponens
│  ├─ app.config.ts          reaktív, NEM titkos konfiguráció
│  └─ error.vue              teljes képernyős hibaoldal
├─ server/                   ← a Nitro-szerver (workerd-ben fut)
│  ├─ api/                   /api/ prefixszel
│  ├─ routes/                prefix NÉLKÜL
│  ├─ middleware/            MINDEN kérésre fut, ábécésorrendben
│  ├─ plugins/               Nitro-életciklus horgok
│  ├─ tasks/                 ütemezett/kézi feladatok
│  └─ utils/                 auto-import a szerveren
├─ shared/                   ← mindkét oldalról elérhető
│  ├─ utils/                 auto-import
│  └─ types/                 auto-import
├─ layers/                   saját rétegek (14. modul)
├─ modules/                  helyi Nuxt-modulok
├─ public/                   érintetlenül kiszolgált fájlok
├─ nuxt.config.ts
└─ wrangler.jsonc            ← a Cloudflare-oldal (17. modul)

A shared/ két szigorú szabálya: (1) csak a shared/utils/ és shared/types/ tartalma importálódik automatikusan, az alkönyvtárak nem — hacsak fel nem veszed őket az imports.dirs ÉS a nitro.imports.dirs listába; (2) a shared/-ban lévő kód nem importálhat sem Vue-, sem Nitro-kódot, mert két külön bundle-be kerül. Minden más fájlt innen kézzel kell importálni a #shared aliassal.

22.2Fájlnév-konvenciók

Oldalak (`app/pages/`)

Fájl	Útvonal	Megjegyzés
`index.vue`	`/`	a könyvtár gyökere
`rolunk.vue`	`/rolunk`	statikus szegmens
`[id].vue`	`/123`	dinamikus szegmens
`[[slug]].vue`	`/` és `/teszt`	opcionális paraméter
`[...slug].vue`	`/a/b/c`	mindent elkapó
`felhasznalo-[csoport]/[id].vue`	`/felhasznalo-admin/123`	szegmensen belüli paraméter
`(marketing)/rolunk.vue`	`/rolunk`	útvonal-csoport — a zárójel nem kerül az URL-be
`szulo.vue` + `szulo/gyerek.vue`	`/szulo/gyerek`	a szülőbe `<NuxtPage />` kell
`szulo/gyerek@oldalsav.vue`	nevesített nézet	a szülő `<NuxtPage name="oldalsav" />`-be renderel

Egyéb utótagok

Minta	Hol	Jelentés
`Valami.client.vue`	komponens	csak a kliensen renderelődik
`Valami.server.vue`	komponens	csak a szerveren (sziget)
`auth.global.ts`	middleware	minden útvonalváltásra fut
`01.setup.client.ts`	plugin	sorrend + csak kliensen
`termekek.get.ts`	server route	csak `GET`
`termekek.post.ts`	server route	csak `POST` (ugyanaz az URL)
`[id].delete.ts`	server route	metódus + paraméter
`10-auth.ts`, `99-proxy.ts`	server middleware	ábécésorrend = futási sorrend

22.3Auto-import: mi, honnan, meddig

Forrás	Hova	Mélység
`app/components/**`	Vue-oldal	tetszőleges — a név a útvonalból áll össze
`app/composables/`	Vue-oldal	legfelső szint + `*/index.ts`
`app/utils/`	Vue-oldal	legfelső szint
`server/utils/`	szerveroldal	legfelső szint
`shared/utils/`, `shared/types/`	mindkettő	legfelső szint
Nuxt beépített composable-ök	Vue-oldal	mindig
h3-segédfüggvények	szerveroldal	mindig
Vue API (`ref`, `computed`…)	Vue-oldal	mindig

Komponensnév-képzés: app/components/bolt/KosarSor.vue → <BoltKosarSor />. A könyvtárnév beépül a névbe, ezért nem ütköznek az azonos nevű komponensek különböző mappákban. Ha ez zavaró, a components: [{ path: '~/components', pathPrefix: false }] kikapcsolja.

22.4Composable-referencia

Terület	Amit használsz
Adatlekérés	`useFetch`, `useLazyFetch`, `useAsyncData`, `useLazyAsyncData`, `$fetch`, `useNuxtData`, `refreshNuxtData`, `clearNuxtData`
Állapot	`useState`, `clearNuxtState`, `useCookie`, `callOnce`
Útvonal	`useRoute`, `useRouter`, `navigateTo`, `abortNavigation`, `definePageMeta`, `addRouteMiddleware`, `setPageLayout`, `useLayout`
Konfiguráció	`useRuntimeConfig`, `useAppConfig`, `updateAppConfig`
Fejléc / SEO	`useHead`, `useHeadSafe`, `useSeoMeta`, `useServerSeoMeta`
Hiba	`createError`, `showError`, `clearError`, `useError`
Kérés (csak szerveren)	`useRequestEvent`, `useRequestHeaders`, `useRequestURL`, `useRequestFetch`, `useResponseHeader`
Életciklus	`useNuxtApp`, `onNuxtReady`, `onPrehydrate`, `reloadNuxtApp`
Betöltés / UX	`useLoadingIndicator`, `useRouteAnnouncer`, `useId`, `usePreviewMode`
Előtöltés	`preloadComponents`, `prefetchComponents`, `preloadRouteComponents`
Definiálók	`defineNuxtPlugin`, `defineNuxtRouteMiddleware`, `defineNuxtComponent`, `defineAppConfig`

A composable-kontextus szabálya (3. modul): a Nuxt composable-jei csak setup-ban, pluginben, middleware-ben vagy defineNuxtRouteMiddleware-ben hívhatók — nem egy await után, és nem eseménykezelőben. A klasszikus hibaüzenet erre a NUXT_E1001; ha mégis kell, nuxtApp.runWithContext().

22.5Komponens-referencia

Komponens	Mire
`<NuxtPage />`	az aktuális oldal helye; szülőoldalban a gyerekútvonalak helye
`<NuxtLayout>`	layout-burkoló; `name` proppal váltható
`<NuxtLink>`	kliensoldali navigáció + automatikus előtöltés
`<ClientOnly>`	csak kliensen renderel; `#fallback` slottal
`<DevOnly>`	csak fejlesztésben renderel, a produkciós buildből kiesik
`<NuxtErrorBoundary>`	lokális hibakezelés; `#error` slot `error` és `clearError` propokkal
`<NuxtLoadingIndicator>`	navigációs folyamatjelző sáv
`<NuxtRouteAnnouncer>`	képernyőolvasóknak jelzi az oldalváltást
`<NuxtIsland>`	szerveroldali sziget, kliens-JS nélkül
`<LazyValami hydrate-* />`	késleltetett hidratálás (15. modul)

Hidratálási stratégiák

Attribútum	Mikor hidratál
`hydrate-on-visible`	amikor a nézetbe kerül
`hydrate-on-idle`	amikor a böngésző tétlen
`hydrate-on-interaction`	első interakcióra (alap: `pointerenter`, `focus`)
`hydrate-on-media-query`	ha a média-lekérdezés illeszkedik
`hydrate-after`	megadott ezredmásodperc után
`hydrate-when`	amikor a kifejezés igazzá válik
`hydrate-never`	soha — a legolcsóbb nyereség

22.6Szerveroldali segédfüggvények

Terület	Függvények
Kezelő	`defineEventHandler`, `defineCachedEventHandler`, `defineCachedFunction`, `defineNitroPlugin`, `defineTask`
Bemenet	`getRouterParam(s)`, `getQuery`, `getValidatedQuery`, `readBody`, `readValidatedBody`, `readRawBody`, `readMultipartFormData`
Kérés	`getRequestURL`, `getRequestIP`, `getHeader`, `getHeaders`, `getCookie`, `getRequestHeaders`
Válasz	`setResponseStatus`, `setResponseHeader(s)`, `appendResponseHeader`, `setCookie`, `deleteCookie`, `sendRedirect`, `sendStream`, `sendNoContent`
Hiba	`createError` — API-route-ból a `message` nem propagál, a `data` igen
Proxy	`proxyRequest`, `sendProxy`, `getProxyRequestHeaders`
Környezet	`useRuntimeConfig(event)`, `useStorage`, `useNitroApp`

Cloudflare-elérés a kezelőben

// Nuxt 4 / Nitro v2
const { env, context, cf } = event.context.cloudflare
env.DB              // bindingok
context.waitUntil(p)  // utómunka a válasz után
cf.country          // geoadat

// Nitro v3-ban ez event.req.runtime.cloudflare.env lesz — tedd wrapper mögé!

22.7`nuxt.config.ts`: a Cloudflare-releváns kulcsok

export default defineNuxtConfig({
  // ——— renderelés ———
  ssr: true,
  routeRules: { /* 22.8 */ },

  // ——— konfiguráció (12. modul) ———
  runtimeConfig: {
    dbUrl: '',                    // szerver-only; NUXT_DB_URL írja felül
    public: { siteUrl: '' },        // kliensre is kimegy!
  },

  // ——— Nitro / Cloudflare ———
  nitro: {
    preset: 'cloudflare_module',
    sourceMap: true,                // alap: false (16.8)
    storage: { /* cache → KV mount, 7. modul */ },
    cloudflare: { wrangler: { /* inline bindingok, 18.3 */ } },
  },

  // ——— teljesítmény / hibakeresés ———
  sourcemap: { client: 'hidden' },  // Sentrynek (20.7)
  experimental: { emitRouteChunkError: 'manual' },
  tracingChannel: true,             // 4.5+ (16.10)

  // ——— környezetek ———
  $production: { /* … */ },
  $development: { /* … */ },
  $env: { staging: { /* --envName staging */ } },

  // ——— újrafelhasználás (14. modul) ———
  extends: ['./layers/alap', 'github:ceg/nuxt-alap#main'],
})

22.8`routeRules` referencia

Szabály	Hatás	Workers-en
`prerender: true`	build-időben HTML-lé	asset lesz, ingyenes — de a middleware nem fut (17.2)
`ssr: false`	üres váz, kliensoldali renderelés	SPA-sziget
`swr: 3600`	elavultat szolgál, közben frissít	KV-mount kell, különben isolate-memória (7. modul)
`isr: 3600`	igény szerinti előrenderelés	ugyanaz a kikötés
`cache: { maxAge }`	Nitro-szintű cache	a tárolót be kell állítani
`headers: {…}`	válaszfejlécek	itt állítod a `Cache-Control`-t (20.6)
`redirect: '/uj'`	átirányítás	—
`cors: true`	CORS-fejlécek	—
`noScripts: true`	nincs kliens-JS az oldalon	tiszta HTML-oldalakhoz
`appMiddleware: […]`	middleware ki/be útvonalanként	—

22.9Parancsok

Parancs	Mire
`nuxt dev`	fejlesztői szerver HMR-rel (18.2)
`nuxt build`	`.output/` előállítása
`nuxt build --envName staging`	`$env` szerinti build-konfig
`nuxt prepare`	`.nuxt/` és a típusok újragenerálása
`nuxt typecheck`	típusellenőrzés
`nuxt module add <név>`	modul telepítése és bekötése
`wrangler dev`	valódi workerd a `.output`-on; `D` = DevTools
`wrangler dev -e staging`	másik környezet bindingjaival
`wrangler deploy`	feltöltés + azonnali 100% forgalom
`wrangler deploy --dry-run --outdir=.b`	bundle-méret mérése (15. modul)
`wrangler check startup`	indulási profil és méret
`wrangler versions upload`	verzió forgalom nélkül + preview URL
`wrangler versions upload --preview-alias pr-42`	beszédes preview URL
`wrangler versions deploy`	forgalomra állítás, akár fokozatosan
`wrangler rollback <id>`	azonnali visszaállás
`wrangler tail --status error`	élő hibafolyam
`wrangler secret put <KULCS>`	titok feltöltése
`wrangler types --check`	binding-típusok naprakészsége (CI)
`wrangler d1 execute <db> --local --file=…`	lokális seed — a `--local` nélkül ÉLES!

22.10„Melyik kódom hol fut?”

Hol	Build	Szerver (workerd)	Kliens
`nuxt.config.ts`	igen	nem	nem
`modules/`	igen	nem	nem
`server/**`	nem	igen	nem
`app/pages/`, `components/`	nem	igen (SSR)	igen
`app/composables/`, `utils/`	nem	igen	igen
`app/middleware/`	nem	igen (első kérés)	igen (navigáció)
`app/plugins/*.ts`	nem	igen	igen
`*.client.ts` / `.client.vue`	nem	nem	igen
`*.server.ts` / `.server.vue`	nem	igen	nem
`shared/**`	nem	igen	igen
`public/`	nem fut — statikus asset, ingyenes (17.1)

A középső sáv a veszélyzóna. Ami mindkét oszlopban zöld, az kétszer fut le: egyszer a Workerben, egyszer a böngészőben. Ide nem való titok (12. modul), nem való modul-szintű mutable állapot (6. modul), és nem való nem-determinisztikus érték (6. modul hidratálási eltérései). Ha egy kód helyét nem tudod megmondani ebből a táblából, ne írj bele semmit, ami számít.

22.11A tanfolyam térképe

Modul	A kérdés, amire válaszol
1	Miért Nuxt a Vue SPA + Express helyett, és mit fizetek érte?
2	Mi történik a `nuxt build` alatt, és mi hol fut?
3	Mit kell másképp csinálnom, mint Vue-ban?
4	Hogyan lesz a fájlokból útvonal, és melyik „middleware” véd tényleg?
5	Hogyan kérek le adatot úgy, hogy ne fusson kétszer?
6	Hova tartozik az állapot, és miért látja egyik felhasználó a másikét?
7	Melyik oldal renderelődjön mikor, és mit tud ebből Workers?
8	Hogyan írok API-t Express helyett h3-mal?
9	Full-stack Nuxt vagy megmaradó külön API?
10	Hogyan oldom meg a bejelentkezést szerver-session nélkül?
11	Hogyan érem el az adatbázist, és melyik ORM-mel?
12	Hol lakik a konfiguráció, és mi nem szivároghat ki?
13	Melyik npm-modul fog működni Workers-en?
14	Hogyan használok újra kódot több projekt vagy tenant között?
15	Mitől lassú, és melyik számot kell mérnem?
16	Hogyan tesztelek és keresek hibát — és mit nem lát a tesztem?
17	Hogyan megy ki élesbe úgy, hogy vissza is tudjak lépni?
18	Hogyan fejlesztek lokálisan valódi bindingokkal?
19	Miért történik ez a furcsaság? (katalógus)
20	Mi kell ahhoz, hogy élesben ne érjen meglepetés?
21	Hogyan költöztetem át a meglévő rendszeremet leállás nélkül?
22	Hol volt az a konvenció? (ez a modul)

22.12Hova tovább

Az öt szabály, ami a huszonkét modulból megmarad

Tudd, hol fut a kódod. A 22.10-es tábla középső sávja a legtöbb rejtélyes hiba forrása. Ha nem tudod megmondani, hol fut egy sor, ne bízz rá semmi fontosat.
Semmi mutable a modul-scope-ban. Egy szabály, két független indok: biztonság (kereszt-kérés szivárgás) és teljesítmény (minden hidegindításkor lefut).
A tesztkészleted Node-ban fut, az appod nem. Az egyetlen teszt, ami a valóságról szól, a valódi deploy ellen futó füstteszt — és a host opció miatt ez ugyanaz a fájl.
Hitelesített oldalt soha ne cache-elj megosztott cache-ben. Ez a tanfolyam egyetlen olyan hibája, ami nem lassulás, hanem adatszivárgás.
A korlátok nem ellenségek. A CPU-limit, a bundle-limit és az isolate-modell olyan fegyelmet kényszerít ki, ami Node-ban is jó gyakorlat lenne — csak ott semmi nem kényszerít rá.

Ami innen következik, az már nem tananyag, hanem gyakorlat. Két javaslat a folytatásra:

Kezdd a 21. modul 0. fázisával, akkor is, ha még nem migrálsz semmit: állítsd fel a vázat, a CI-t, a preview-deployt és a füsttesztet üresen. Ez a lánc az, ami minden későbbi lépést olcsóvá tesz — és amit utólag beépíteni sokkal fájdalmasabb.
Mérj a második naptól. A bundle-méret, az indulási idő és a CPU-idő trendje csak akkor mond valamit, ha van mihez képest. Egy üres app mérőszáma is adat.

És egy záró megjegyzés a verziókról. Ez az anyag 2026 augusztusában készült, Nuxt 4.5-re és a Nitro v2-es vonalra. A Nitro v3 (és vele a Nuxt 5) néhány dolgot át fog nevezni — a legfontosabb az event.context.cloudflare → event.req.runtime.cloudflare váltás. Ezért javasoltam több helyen is, hogy a bindingokhoz és a Cloudflare-kontextushoz saját segédfüggvényen keresztül nyúlj. Ha ezt megfogadtad, a váltás egy fájl átírása lesz — ha nem, hetvené.

Előző21. modul — Migrációs recept: Vue SPA + Express → Nuxt KövetkezőEz az utolsó modul

↑