Nuxt-fejlesztés Cloudflare-en

13.1A motorháztető alatt: mi történik nuxt build-kor?

A Nuxt szerveroldali motorja a Nitro, és a lényeg egyetlen szóban: preset. A Nitro egy platformfüggetlen szerver-réteget épít a kódodból, majd a preset megmondja, milyen „csomagolásban" adja ki — Node-szerverként, Lambda-handlerként, vagy éppen Worker-modulként. A te kódod (az server/api/*, a middleware-ek, az SSR) nem tud arról, hol fog futni; a fordítás lépése dönt.

Amit a preset konkrétan elintéz helyetted:

• Egyetlen modullá bundle-ol (rollup) — a Workers 10 MB-os méretkorlátja miatt ez nem mellékes; tree-shaking, minifikálás.
• A handler-alakot előállítja: a Nitro belső h3 app-ját becsomagolja a Workers export default { fetch } formába — beleértve a scheduled és queue handlereket is, ha vannak (7. modul).
• A Cloudflare-kontextust átvezeti: a request, az env (bindingok!) és a ctx (ExecutionContext) bekerül a H3 event kontextusába — innen éred el őket a kódodban.
• A statikus assetek kiszolgálását a platformra bízza (3. modul: asset-first routing), nem a Worker-kódra.
• Node-polyfilleket injektál, ahol tud (a nodejs_compat mellé).

13.2Presetek: melyiket mikor?

13.3A projekt felállítása

Nulláról

npm create cloudflare@latest -- my-app --framework=nuxt
# → Nuxt projekt, Cloudflare-re konfigurálva: preset, wrangler.jsonc, dev-modul, scriptek

Meglévő Nuxt-app átállítása — a négy fájl, amihez hozzá kell nyúlni

1) nuxt.config.ts — a preset és a dev-modul:

export default defineNuxtConfig({
  nitro: {
    preset: "cloudflare_module",
    cloudflare: {
      deployConfig: true,        // a Nitro szinkronban tartja a wrangler-konfigot
      nodeCompat: true            // nodejs_compat bekapcsolása
    }
  },
  modules: ["nitro-cloudflare-dev"]  // bindingok a `nuxt dev` alatt (13.4)
});

2) wrangler.jsonc — a 12. modul szerint; a Nuxt-specifikus rész a két útvonal:

{
  "name": "my-app",
  "main": "./.output/server/index.mjs",   // a Nitro által generált Worker
  "compatibility_date": "2026-08-04",
  "compatibility_flags": ["nodejs_compat"],
  "assets": { "directory": "./.output/public", "binding": "ASSETS" },
  "observability": { "enabled": true },
  "upload_source_maps": true
  // + bindingok és env-ek (12. modul)
}

3) package.json — a scriptek, amik a csapat napi felületét adják:

{
  "scripts": {
    "dev": "wrangler types && nuxt dev",
    "build": "nuxt build",
    "preview": "nuxt build && wrangler dev",          // éles-szerű futtatás lokálisan
    "deploy:staging": "nuxt build && wrangler deploy --env staging",
    "deploy:prod": "nuxt build && wrangler deploy --env production",
    "cf-typegen": "wrangler types"
  }
}

4) .gitignore — a szokásos .nuxt, .output mellé: .dev.vars*, .wrangler/.

13.4A dev-környezet — két út, és melyiket válaszd

Ez az a pont, ahol a Nuxt+Cloudflare ökoszisztéma épp átalakulóban van, ezért érdemes tudni, mi a különbség:

Ajánlás: ma az (A) a biztos alapfelállás a napi fejlesztéshez, és mellé egy „élesség-ellenőrző" lépés: npm run preview (nuxt build && wrangler dev), ami a buildelt Workert futtatja a valódi workerd-ben. Így a gyors hurok megmarad, de commit előtt látod, hogy a runtime-különbségek nem harapnak. Ha a projekted már a Vite-plugin útra állt (vagy új projektet kezdesz), (B) a jövőálló irány.

Titkok és környezeti változók lokálisan

# .dev.vars — NEM megy a repóba
STRIPE_SECRET_KEY="sk_test_…"
NUXT_SESSION_PASSWORD="legalabb-32-karakter-hosszu-titok"

A .dev.vars értékei ugyanúgy az env-en jelennek meg, mint élesben a wrangler secret-tel feltöltöttek. A NUXT_-prefixű változókat a Nitro ezen felül beleköti a runtimeConfig-ba — erről lentebb.

Remote bindings — ha valódi adat kell

A 11. modulból ismerős: bindingonként "remote": true, és az adott erőforrás az éles (staging!) példány lesz, miközben a Nuxt lokálisan fut. Tipikus eset: lokális D1, de valódi R2 vagy AI-binding.

13.5Bindings a Nuxt-kódban — hova tedd, hogy ne fájjon

A nyers hozzáférés így néz ki bármelyik server route-ban:

export default defineEventHandler(async (event) => {
  const { env, cf, context } = event.context.cloudflare;
  // env.DB, env.UPLOADS, env.JOBS… — a 12. modulban deklarált bindingok
  // cf: ország, colo, TLS-adatok…  context: waitUntil (2. modul)
});

Típusok

Futtasd a wrangler types-t, majd egyszer deklaráld a H3-kontextust — innentől az env.DB típusos mindenhol:

declare module "h3" {
  interface H3EventContext {
    cf: CfProperties;
    cloudflare: {
      request: Request;
      env: Env;                 // a `wrangler types` által generált típus
      context: ExecutionContext;
    };
  }
}
export {};

A minta, ami megment a szétszórt event.context.cloudflare.env-től

Ne szórd tele az egész kódbázist a Cloudflare-specifikus eléréssel — vezess be egy vékony hozzáférési réteget a server/utils/-ban (a Nitro ezt auto-importálja):

import type { H3Event } from "h3";

export const cf = (event: H3Event) => event.context.cloudflare;

export const useDb = (event: H3Event) => cf(event).env.DB;
export const useBucket = (event: H3Event) => cf(event).env.UPLOADS;

// háttérmunka: a válasz után is befejeződik (2. modul)
export const background = (event: H3Event, p: Promise<unknown>) =>
  cf(event).context.waitUntil(p);

// tenant-feloldás egy helyen (5b. modul mintája)
export async function useTenant(event: H3Event) {
  const host = getRequestHost(event);
  const slug = host.split(".")[0];
  const cached = await cf(event).env.CONFIG.get(`tenant:${slug}`, { type: "json" });
  if (cached) return cached;
  // … registry-lookup + KV-cache (6. modul)
}

export default defineEventHandler(async (event) => {
  const tenant = await useTenant(event);
  const { results } = await useDb(event)
    .prepare("SELECT * FROM invoices WHERE tenant_id = ? ORDER BY created_at DESC")
    .bind(tenant.id).all();

  background(event, logAccess(event, tenant.id));
  return results;
});

runtimeConfig vs. bindings vs. secrets — mikor melyik?

Gyakorlat: a Cloudflare-erőforrásokhoz mindig bindingot használj. A runtimeConfig-ot arra tartsd, amire a Nuxt-világ szánta: kliens felé publikálható beállítások (public), illetve olyan szerveroldali értékek, amiket Nuxt-modulok várnak (pl. session-jelszó). Így nem lesz két párhuzamos konfig-rendszered ugyanarra.

13.6Nitro-specialitások Cloudflare-en

Cache és routeRules

export default defineNuxtConfig({
  routeRules: {
    "/":            { swr: 600 },
    "/blog/**":     { isr: 3600 },
    "/app/**":      { ssr: true, cache: false },   // bejelentkezett rész
    "/docs/**":     { prerender: true },            // build-időben generált
    "/api/**":      { cors: true }
  }
});

A cache-elt válaszok tárolására a Nitro a platform cache-ét használja. Fontos árnyalat: az isr/swr a PoP-onkénti cache-re támaszkodik, tehát nem globálisan egy példány frissül — ha szigorúan egységes időzítés kell, azt jobb explicit KV-be tett generált tartalommal megoldani.

useStorage() — a Nitro tárolási absztrakciója

Ha a Nitro useStorage()-ét használod (cache, sessionok, kulcs-érték adat), Cloudflare-en driverrel köthető KV-hez vagy R2-hez:

nitro: {
  storage: {
    cache:   { driver: "cloudflare-kv-binding", binding: "CONFIG" },
    uploads: { driver: "cloudflare-r2-binding",  binding: "UPLOADS" }
  }
}

WebSocket és háttérfeladatok

A Nitro WebSocket-támogatásához és a tartós kapcsolatokhoz Cloudflare-en Durable Object kell — erre való a cloudflare_durable preset. Ha komolyabb realtime funkciód lesz (jelenlét, kollaboráció), érdemes inkább saját DO-t írni a 7. modul mintái szerint, és a Nuxt-ot csak kliens-oldali kapcsolódásra használni: átláthatóbb és jobban skálázható.

Cron és queue a Nuxt-projektben

A Nitro `scheduled`/`queue` handlerei a generált Workerbe kerülnek. A gyakorlatban két járható út van: vagy a Nitro task-jait használod és a wrangler-konfigban felveszed a triggers.crons-t, vagy — nagyobb rendszernél tisztább — a háttérmunkát külön Workerbe teszed, és service bindinggel kötöd össze (11. modul). Utóbbi mellett szól, hogy a háttér-Workert külön deployolhatod, külön limitekkel és külön skálázással.

13.7NuxtHub — kell?

A NuxtHub egy Nuxt-réteg a Cloudflare-primitívek fölött: `hubDatabase()` (D1), `hubKV()`, `hubBlob()` (R2), `hubAI()` — plusz admin-felület és egyszerűsített deploy. A mérleg:

Az ajánlásom a te helyzetedben: maradj a natív bindingoknál. Egy meglévő, éles multitenant SaaS-nál a saját hozzáférési rétegedet (13.5) úgyis megírod, az pontosan illik a te modelledhez, és nem függ egy köztes csomag életciklusától. A NuxtHub új, kisebb projektnél vagy prototípusnál viszont teljesen jó választás.

13.8Projekt-struktúra — ajánlás multitenant SaaS-hoz

Két elv, ami sokat számít éles rendszerben: ① a server/api maradjon vékony — validálás + hívás a server/utils-beli üzleti függvényre; így a logikád tesztelhető marad a HTTP-rétegtől függetlenül (11. modul). ② a tenant-feloldás middleware-ben történjen, egyszer, és az eredmény kerüljön az event kontextusába — ne minden endpoint oldja meg újra.

13.9Deploy

# kézzel
npm run build
npx wrangler deploy --env production

# előtte érdemes: éles-szerű lokális ellenőrzés
npm run preview            # nuxt build && wrangler dev

Workers Builds beállítás Nuxthoz (8. modul):

A séma-migrációk itt is a 8. modul szabálya szerint mennek: a deploy előtt, külön lépésben, stagingen automatikusan, éles környezetben kapuval.

13.10Buktatók — Nuxt-specifikus katalógus

13.11Ellenőrizd magad