A Nuxt anatómiája: mi épül, és mi hol fut

2.1A három futásidő

Vue SPA-ban egyetlen futásidő van: a böngésző. Nuxtban három, és ezek különböző időpontokban, különböző környezetben futnak — más globális objektumokkal, más API-kkal, más korlátokkal.

A középső sáv a kritikus. Egy komponens <script setup> blokkja kétszer fut le: egyszer a szerveren az SSR alatt, egyszer a böngészőben a hydration alatt. Ha a kettő nem ugyanazt az eredményt adja, hydration mismatch lesz belőle. Ha valami olyat használsz, ami csak az egyik helyen létezik (window, vagy fordítva: egy adatbázis-kliens), akkor hiba.

2.2Mi történik nuxt build-kor

A build nem egy lépés, hanem négy, és a hibaüzenetek attól függően néznek ki, hogy melyikben akadtál el:

Két dolgot érdemes ebből megjegyezni. Egyrészt a .nuxt/ nem szemét, hanem a fordítás félkész terméke: itt találod a generált route-táblát, az auto-import térképet és a típusokat. Amikor nem érted, honnan jön egy useValami(), ide nézel. Másrészt a kliens- és a szerverkód külön bundle — ezért fordulhat elő, hogy valami a böngészőben megy, a szerveren nem, vagy fordítva.

2.3Mi kerül a .output/-ba

Ez a deploy-artefakt. Semmi mást nem kell feltölteni, és semmit nem kell benne kézzel módosítani (a következő build felülírja):

.output/
├─ public/                 ← statikus fájlok — ez lesz a Workers static assets
│  ├─ _nuxt/                  a buildelt JS/CSS chunkok, hash-elt névvel
│  │  ├─ entry.C3f1a9.js
│  │  └─ default.a71b2c.css
│  ├─ favicon.ico             a public/ mappád tartalma változatlanul
│  └─ ...                     plusz a prerenderelt oldalak, ha vannak
├─ server/
│  ├─ index.mjs            ← A BELÉPÉSI PONT. Workers-en ez a Worker modul.
│  └─ chunks/                 a szerverkód darabjai (SSR + server/api)
└─ nitro.json                 metaadat: melyik presettel készült, verziók

Node-szerveren ezt így indítanád: node .output/server/index.mjs. Workers-en viszont ugyanez az index.mjs nem egy szerver, amit elindítasz, hanem egy Worker-modul, amit a platform hív meg — a wrangler.jsonc-ben ez lesz a main, a .output/public pedig az assets.directory. A 17. modulban ezt kirakjuk teljes konfigurációval.

2.4Melyik kódom hol fut? — a referencia-tábla

Ezt tedd a könyvjelzők közé. A tananyag hátralévő részében erre fogok visszautalni:

A gyakorlati eszköz: import.meta

Amikor kódban kell eldöntened, hol vagy:

const width = ref(0)

// ✗ így szokták — működik, de nem tree-shake-elhető, és a szerverbundle-ben is ott marad
if (typeof window !== 'undefined') width.value = window.innerWidth

// ✓ így kell — a build ki tudja dobni a nem oda való ágat
if (import.meta.client) width.value = window.innerWidth

// a teljes készlet
import.meta.client      // böngészőben fut
import.meta.server      // szerveren fut (SSR vagy server route)
import.meta.dev         // nuxt dev alatt
import.meta.prerender   // build-time prerender közben

A régi process.server / process.client párost felejtsd el — nem véletlenül tűnt el: Workers-en nincs értelmes process globális, és a Nuxt 5 felé az import.meta.* a járható út.

2.5A Nuxt 4 könyvtárszerkezete

A Nuxt 4 legfeltűnőbb változása, hogy az alkalmazás-kód bekerült egy app/ mappába. Nem esztétikai döntés: így a fájlfigyelő nem a node_modules/ és a .git/ mellett kutat, és a szerver-, kliens- és megosztott kód szétválasztása a TypeScript-projektek szintjén is megtörténik.

a-projekted/
├─ app/                    ← ALKALMAZÁS (kliens + SSR)
│  ├─ app.vue                 a gyökérkomponens
│  ├─ pages/                  route-ok (4. modul)
│  ├─ layouts/
│  ├─ components/             auto-import
│  ├─ composables/            auto-import
│  ├─ middleware/             route middleware
│  ├─ plugins/
│  ├─ utils/                  auto-import
│  └─ assets/                 amin átmegy a build (SCSS, kép)
├─ server/                 ← SZERVER — a gyökérben marad, NEM az app/ alatt
│  ├─ api/
│  ├─ routes/
│  ├─ middleware/
│  ├─ utils/                  auto-import, csak szerveroldalon
│  └─ plugins/                Nitro-pluginek (nem app-pluginek!)
├─ shared/                 ← KÖZÖS: típusok, tiszta függvények (Nuxt 4)
├─ public/                    változatlanul kikerül
├─ modules/                   saját build-idejű Nuxt-modulok
├─ nuxt.config.ts
├─ wrangler.jsonc             a Cloudflare-oldal (17. modul)
└─ tsconfig.json              egyetlen fájl a gyökérben, a többit a Nuxt generálja

2.6Nitro és a presetek

A Nitro a Nuxt szerver-rétege — de önálló projekt, saját életet él. Ő felel a server/api útvonalakért, a fájl-alapú szerver-routingért, a storage-rétegért (useStorage()), a cache-elésért, és a platformra szabott csomagolásért.

Ez utóbbi a preset-rendszer. Ugyanaz a forráskód különböző kimenetté fordul aszerint, hova megy:

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare_module',   // Workers + static assets — ez kell nekünk
  },
})

// vagy környezeti változóból, CI-ben:
// NITRO_PRESET=cloudflare_module nuxt build

A cloudflare_module preset Workersre épít (ez az ajánlott út); a régebbi cloudflare_pages a Pages-hez tartozik, ami a Cloudflare-anyag szerint kifutó irány. A preset dönti el, hogy milyen belépési pont készül, milyen polyfillek kellenek, hogyan viselkedik a useStorage(), és mit tud a beépített cache-réteg.

2.7nuxt dev — és miért „ment lokálisan”

A fejlesztői szerver nem ugyanaz, ami élesben fut, és a különbség pont Workers-en a legnagyobb:

Innen ered a leggyakoribb frusztráció: „lokálisan tökéletesen ment, deploy után 500-as”. Nem véletlen, hanem szerkezeti: dev alatt a szerverkódod Node-ban fut, élesben a workerd-ben. Két dolog véd ellene, és mindkettőt korán érdemes bevezetni:

• Emuláld a platformot fejlesztés közben — nitro-cloudflare-dev vagy a Cloudflare Vite plugin. Ettől lesznek bindingjaid lokálisan is, és sok Node-only feltételezés már itt kibukik. A 18. modul összeveti a kettőt.
• Deployolj korán és sűrűn preview URL-re. Ne az első éles kiadás legyen az első alkalom, hogy a kódod workerd-ben fut. Ez a Cloudflare-anyag 8. moduljának preview-mechanikája.

2.8Felkészülés a Nuxt 5-re — anélkül, hogy rá várnánk

A Nuxt 5 a Nitro v3-mal együtt érkezik, és még nincs kint; a 4.5 már tartalmaz hozzá előkészítést. Nem érdemes rá várni — viszont van négy szokás, amivel most, ingyen csökkented a jövőbeli migráció költségét:

• Használd az import.meta.client / import.meta.server párost, ne a process.*-ot.
• Ne nyúlj a .nuxt/ belsőségeihez. Olvasni jó, támaszkodni rá rossz — ezek a generált fájlok verzióról verzióra változnak.
• Maradj a legfrissebb 4.x-en. A minor kiadások hozzák a deprecation-figyelmeztetéseket; ezek a migráció ingyenes térképe.
• Nézd meg a moduljaid karbantartottságát, mielőtt beveszed őket. Egy elhagyott modul a következő majornál lesz a te dolgod (1.3-as szakasz).

2.9Ellenőrizd magad