Gyakorlati Nuxt-tananyag ahhoz az esethez, amikor a cél nem „egy Nuxt app valahol”, hanem egy Nuxt app a Cloudflare Workers-en. Végig ez az ív: minden döntésnél az számít, hogy a végén az edge-en fog futni.
Három dolgot vettem alapul, és ezek végig érződni fognak az anyagon:
useState vs. ref, és az SSR miatt máshogy viselkedő kód.nuxi generate), Node-szerveres deploy PM2/Docker mellett, Vercel/Netlify-specifikus finomságok, Nuxt 2 / Options API. Ezeket vagy kihagyom, vagy egy mondatban intézem el — a helyükre több Cloudflare-specifikus tartalom kerül.Ahogy a Cloudflare-anyagnál az AWS-megfeleltetés, itt ez a tábla a gyors tájékozódás: amit ma Vue SPA + Express környezetben kézzel raksz össze, annak mi a Nuxt-beli megfelelője.
| Amit ma csinálsz | Nuxt-megfelelő | Modul |
|---|---|---|
| vue-router konfig, route-tábla kézzel | fájl-alapú routing az app/pages/ alatt, nested layoutokkal | 4 |
axios a komponensben, onMounted-ben | useFetch / useAsyncData — már a szerveren lefut, nincs loading-villanás | 5 |
| Vuex/Pinia store minden globális állapotra | useState (SSR-biztos), Pinia csak ahol tényleg kell | 6 |
| Express router + controllerek | server/api/*.ts, defineEventHandler (h3) | 8 |
| Express middleware (auth, log, rate limit) | server/middleware/ + route middleware a kliensoldalon | 8, 10 |
passport + express-session + Redis | lezárt (sealed) cookie-session, nuxt-auth-utils / better-auth | 10 |
cors, helmet csomagok | h3 utils + routeRules (cors, headers) | 7, 8 |
| Vite/Webpack konfig kézzel | nuxt.config.ts + modulok (Vite 8 fut alatta) | 12, 13 |
index.html, meta tagek, sitemap kézzel | useSeoMeta / useHead — szerveroldalon renderelve | 20 |
.env + process.env mindenhol | runtimeConfig, és Workers-en bindings + secrets | 12, 19 |
nodemon + külön frontend dev-szerver | egy nuxt dev, HMR-rel — lokálisan is valódi bindingokkal | 18 |
| nginx + PM2 + statikus mappa + CDN | egyetlen Workers-deploy: SSR és a statikus assetek együtt | 17 |
Fontos, mert pont most volt egy éles határ:
NUXT_E1001 típusú), a useLayout composable-t, a named view-kat, és az enabled opciót a useFetch/useAsyncData-hoz.app/ könyvtárszerkezettel dolgozik.A tényleges összevetés: Vue SPA + Express vs. Nuxt. Mit ad hozzá (SSR és a hydration értelme, fájl-alapú routing, auto-import, beépített szerver, build-pipeline, modulrendszer, konvenciók), és mit veszítesz (keretrendszer-kötöttség, „mágia”, nehezebb debug, upgrade-adósság) — mert enélkül nem döntés, csak hype. Röviden a Next.js/SvelteKit-összevetés is. Végül a lényeg: miért illik a Nuxt kifejezetten jól a Workers-hez — egyetlen deploy-artefakt, SSR az edge-en, nincs külön CDN-réteg.
itt kezdjükvs. Vue + ExpressA motorháztető alatt: mi történik nuxt dev és nuxt build közben, mit generál a .nuxt/ és mi kerül a .output/-ba. A három futásidő szétválasztása (build-time, szerver, kliens) — ez az a modell, ami nélkül minden SSR-hiba érthetetlen marad. Nitro mint a szerver-réteg, presetek. A Nuxt 4 könyvtárszerkezete (app/, server/, shared/) és hogy miért lett így. Verzióhelyzet és a Nuxt 5 / Nitro v3 felkészülés.
Amit tudsz, az megmarad — de hét ponton máshogy kell gondolkodni: auto-import (és mikor harap vissza), composables/ konvenció, useState vs. ref és miért nem mindegy szerveren, definePageMeta, plugin-ok és a .client/.server utótagok, a window/document elérés szabályai, és a hydration mismatch — a leggyakoribb hiba, amit Vue-ból érkezve elkövetsz. Konkrét „ezt így írtad volna, helyette így” példákkal.
Fájl-alapú routing a gyakorlatban: dinamikus és catch-all szegmensek, nested route-ok, route groups, named views (4.5). Layoutok és a useLayout. A háromféle middleware (globális, névvel hivatkozott, inline) és hol fut mindegyik — szerveren, kliensen, vagy mindkettőn. <NuxtLink> és a prefetch (plusz mikor kapcsold ki). Multitenant útvonaltervezés: /t/:tenant/… vs. subdomain vs. egyedi domain — melyiket hogyan kezeld Nuxtban.
A tananyag legfontosabb modulja. Melyik mikor, és miért: a három eszköz pontos szerepe, a key jelentősége, reaktív kulcsok, enabled (4.5), transform, pick, getCachedData, lazy és server:false. Miért fut le kétszer az adatlekérésed, és hogyan kerüld el. Hibakezelés és useError. Végül a legkevésbé ismert csapda: a payload — mi utazik ki a HTML-be a szerveri lekérésből, és hogyan szivárogtatsz vele véletlenül más tenant adatát.
useState mint SSR-biztos alapeszköz, és miért nem szabad modulszintű ref-et használni globális állapotra — a cross-request state pollution, vagyis amikor az egyik felhasználó adata átszivárog a másikhoz, mert a szerveren a modul-scope megosztott. Mikor kell tényleg Pinia, és hogyan használd SSR-rel. useCookie és a cookie-alapú állapot. Állapot és tenant-kontextus együtt.
routeRules — a Cloudflare-valósággalUniversal SSR, SPA-mód, prerender, és a hibrid renderelés útvonalanként. A routeRules teljes eszköztára (prerender, ssr, isr, swr, cache, headers, cors, redirect, noScripts). És az őszinte rész: az ISR/SWR platform-natívan Vercel/Netlify alatt működik — Workers-en mást jelent, más a tárolója és más a viselkedése. Megmutatom, mi működik, mi nem, és mit használj helyette (Workers cache, KV). Streaming SSR (4.5, kísérleti) és hogy Workers-en mit ér.
server/api/ és server/routes/, defineEventHandler, az event-objektum felépítése. Body, query, route-paraméterek, fejlécek, cookie-k, streamelt válasz. Validáció (zod/valibot) és a hibakezelés createError-ral. Server middleware és amiben más, mint az Express-é. server/utils/ és az auto-import. Teljes Express → h3 megfeleltetési tábla a leggyakoribb mintákra, plusz a fájlfeltöltés és a webhook-fogadás gyakorlata.
A tananyag elágazása. Az egyik út: a Nitro server routes kiváltja az Express API-t, minden egy deploy-egységben. A másik: a Nuxt SSR/BFF rétegként fut, a meglévő API mögötte marad. Végigvezetem mindkettőt a te multitenant SaaS-odra vetítve — csapatméret, migrációs kockázat, mobil-/partner-kliensek, közös típusok, hívási latency Workers-ről a régi API felé, üzemeltetési költség. Plusz a legvalószínűbb válasz: a hibrid, és hogy hol húzd meg a határt. Döntési checklist a végén.
architekturális elágazásMiért nem egy az egyben átültethető a passport + express-session + Redis minta. A lezárt cookie-session (nuxt-auth-utils), a better-auth mérlege, és a szerveroldali védelem: miért nem elég a kliensoldali route middleware, és mit kell mindig a server/-ben ellenőrizni. Tenant-feloldás és tagság-ellenőrzés a kérés életciklusában. CSRF, kijelentkeztetés, session-visszavonás. Mi működik ebből Workers-en — és mi nem (a jelszó-hashelés kérdése).
server/-benHogyan éred el a Cloudflare-erőforrásokat Nuxtból: event.context.cloudflare.env, saját server/utils/db.ts wrapper, Drizzle D1-gyel és Hyperdrive-val, kapcsolat-életciklus kérésenként. Típusok generálása a bindingokhoz. A vasszabály: mit nem szabad importálni a szerverkódba (Node-only csomagok), és hogyan derül ez ki csak deploy után, ha nem figyelsz. Tranzakciók és a batch-minta. Lokális vs. távoli erőforrás fejlesztés közben.
nuxt.config.ts, runtimeConfig, TypeScriptA konfigfájl végigvezetve, a gyakorlatban tényleg használt opciókkal. A négy szint szétválasztása: build-time konstans vs. runtimeConfig vs. környezeti változó vs. Cloudflare binding/secret — melyik mikor, és melyik szivárog ki a kliensbe. app.config.ts vs. runtimeConfig. A Nuxt 4 TypeScript-felállása (külön projektek app/server/shared kódra), aliasok, a shared/ könyvtár és a közös típusok kliens és szerver között.
Nem katalógus, hanem szűrt lista Workers-szemmel. Amit ajánlok és miért: @nuxt/image (és hogy Workers-en hogyan oldd meg — sharp ott nem fut), @nuxtjs/i18n, @nuxt/fonts, @vueuse/nuxt, @pinia/nuxt, UI-könyvtár kérdés (@nuxt/ui vs. saját). Amivel vigyázz: @nuxt/content és a fájlrendszer-igényes modulok. Végül: hogyan írj saját modult, ha ismétlődő setupod van.
A Nuxt egyik legalulértékeltebb képessége, és ami a te esetedben kifejezetten releváns: layerekkel egy alap-app fölé húzhatók tenant- vagy márkaspecifikus rétegek (téma, komponens-felülírás, extra oldalak) anélkül, hogy külön kódbázist tartanál fenn. Hogyan működik az extends, mi a feloldási sorrend, mit lehet felülírni és mit nem. Monorepo-felállás, és a buktatók (build-idő, verziózás, a „melyik fájl nyer” kérdés).
Hol vész el a Nuxt-appok sebessége: a hydration költsége és hogyan csökkentsd (<ClientOnly>, lazy komponensek, szigetek), a payload mérete és a payloadExtraction, komponens-szintű kódszeletelés, képek. Mérés Lighthouse-zal és a Core Web Vitals reális célszámai. És a Cloudflare-specifikus rész: a bundle-méret limit, mi fogyasztja el, hogyan mérd, és mit tegyél, ha átléped — plusz a cold start valósága Workers-en.
@nuxt/test-utils és a Vitest-felállás, komponens-tesztek, szerver-route tesztelése, és mennyi tesztet érdemes írni egy ilyen appra. Hibakeresés: a Nuxt 4.5 stabil hibakódjai, SSR-only hibák előhívása lokálisan, hydration mismatch felderítése lépésről lépésre, Vue DevTools és a Nuxt DevTools. Végül a nehéz eset: hiba, ami csak Workers-en jelentkezik — hogyan szűkítsd le.
Az első éles deploy végig: preset-választás, a wrangler.jsonc Nuxt-projekthez, static assets és a routing-sorrend (mikor fut a Worker és mikor jön statikus fájl), a build-output anatómiája. Preview URL-ek PR-onként, custom domain, környezetek. Amit a Cloudflare-anyag már lefedett, arra hivatkozom — itt a Nuxt-specifikus rész van kibontva, plusz a tipikus „lokálisan ment, deploy után 500-as” esetek katalógusa.
A két út összevetése: nitro-cloudflare-dev (getPlatformProxy) vs. a Cloudflare Vite plugin — melyik mit szimulál, hol térnek el, melyiket válaszd. Lokális vs. távoli (remote) erőforrások és mikor melyik kell. Secretek fejlesztés közben. A dev és a prod közti maradék eltérések listája — mert lesznek, és jobb tudni, melyek azok.
A gyűjtőmodul mindenről, ami a szokásos Nuxt-recepteket felülírja: Node-API-k és a nodejs_compat határai, a nem működő csomagok (sharp, bcrypt, fájlrendszer-igényes libek) és a helyettesítésük, useStorage() driverek (KV, R2) a Node-os fs helyett, process.env vs. bindings, CPU-idő és a hosszú SSR, cold start, a 6 párhuzamos kimenő kapcsolat. Diagnosztikai recept: hogyan derítsd ki gyorsan, hogy egy hiba Nuxt- vagy platform-eredetű.
Ami az indulás előtt kell. SEO Nuxtban (useSeoMeta, canonical egyedi tenant-domaineknél, sitemap és robots dinamikusan generálva, strukturált adat). i18n a cache-biztos módon. Cache-stratégia rétegenként: mit cache-elj a Workers-cache-ben, mit a Nitro storage-ban, és hol a személyre szabott tartalom határa. Hibakövetés és logolás Nuxt-oldalról (Nitro hookok, globális error handler, mit logolj és mit nem). Éles indulás előtti checklist.
Fázisokra bontott, visszafordítható terv. Mit vigyél át először (és miért nem az auth-ot), hogyan futhat a régi és az új párhuzamosan, útvonalankénti átterelés, a közös session kérdése az átmenetben, adatbázis-hozzáférés a két rendszerből, és a forgalom átkapcsolásának pillanata. Mérföldkövek, visszafordítási pontok, és a reális idővonal — plusz mikor éri meg nem migrálni.
átállási tervVisszakereséshez készült záró modul: minden speciális könyvtár és fájl egy táblázatban (app/, pages/, layouts/, components/, composables/, middleware/, plugins/, server/, shared/, public/, modules/, utils/) — mi kerül bele, mikor fut, mi importálódik automatikusan. Mellette a leggyakoribb composable-ok gyorsreferenciája és a fájlnév-utótagok (.client, .server, .global) jelentése.
nuxi generate) és a tisztán SSG-s hostolásnode .output/server/index.mjs@nuxtjs/composition-api és a régi ökoszisztéma