Lokális fejlesztés valódi bindingokkal

18.1A hűségi létra

Nem az a cél, hogy a legfelső fokon fejlessz — ott lassú és drága. A cél az, hogy tudd, melyik fokon vagy, és hogy a nap végén felmássz egy fokkal, mielőtt kiadod a munkát a kezedből.

18.2① nuxt dev — amit ad, és amit nem

A Nuxt fejlesztői szervere Node-ban fut, HMR-rel. Ez a rövid visszacsatolási hurok, amiért egyáltalán érdemes Nuxtot használni: elmented a fájlt, és a böngészőben azonnal látod. Ezt semmilyen hűségi nyereményért nem szabad feladni a napi munkában.

Ami itt nincs a helyén: a Cloudflare-bindingok (alaphelyzetben), a workerd futásidő korlátai, a bundle-méret, a hidegindítás. Vagyis a hibák egy egész osztálya láthatatlan — pontosan az, amit a 16.1-es ábra a piros vonal alá tett.

18.3② Bindingok a nuxt dev-ben

Régen ehhez kellett a nitro-cloudflare-dev modul, ami a wrangler getPlatformProxy API-jával pótolta a bindingokat a dev szerverben. Ez ma már elavult — a projekt README-je maga írja ki, hogy „ez a modul már nem szükséges a Nitro legújabb verzióihoz”, mert a Nitro beépítve emulálja a Cloudflare-környezetet Miniflare-rel.

Mivel a Nuxt- és Nitro-verziók között ez a képesség éppen most mozdult át, ne higgy se nekem, se a blogbejegyzéseknek: ellenőrizd le harminc másodperc alatt a saját projekteden.

// server/api/_debug-bindings.get.ts — töröld, mielőtt élesbe megy
export default defineEventHandler((event) => {
  const cf = (event.context as any).cloudflare
  return {
    vanBinding: Boolean(cf?.env),
    kulcsok: cf?.env ? Object.keys(cf.env) : [],
  }
})

npx nuxt dev
curl http://localhost:3000/api/_debug-bindings

Ha nem akarsz külön wrangler.jsonc-t a dev-hez, a bindingokat inline is megadhatod a Nuxt-konfigban:

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare_module',
    cloudflare: {
      wrangler: {
        vars: { APP_MODE: 'dev' },
        kv_namespaces: [{ binding: 'CACHE', id: 'local' }],
        d1_databases: [{ binding: 'DB', database_name: 'bolt', database_id: 'local' }],
      },
      wranglerEnv: 'preview',
    },
  },
})

18.4A lokális adat: hol lakik és hogyan töltöd fel

Az emulált bindingok mögött valódi, lemezre írt állapot van. Alapból a projekted .wrangler/state könyvtárában, KV / R2 / D1 / Durable Object alkönyvtárakra bontva.

# D1: séma és seed betöltése LOKÁLISAN
npx wrangler d1 execute bolt --file=./db/schema.sql --local
npx wrangler d1 execute bolt --command="SELECT count(*) FROM products" --local

# KV: egy kulcs, illetve tömeges betöltés JSON-ből
npx wrangler kv key put feature:uj-checkout "on" --binding=CACHE --local
npx wrangler kv bulk put ./db/kv-seed.json --binding=CACHE --local

# R2: fájl feltöltése a lokális bucketbe
npx wrangler r2 object put bolt-media/logo.png --file=./assets/logo.png --local

# tiszta lap: az egész lokális állapot eldobása
rm -rf .wrangler/state

Ha másik könyvtárba akarod tenni az állapotot, a --persist-to a kapcsoló — de ekkor minden wrangler-parancsnál meg kell ismételned, különben a seed egy másik adatbázisba megy, mint amit a dev szerver olvas. Ez a leggyakoribb „de hát épp most töltöttem fel!” pillanat.

18.5Titkok lokálisan: .dev.vars

Az éles secretek wrangler secret put-tal mennek fel (17.8). Lokálisan viszont fájlból jönnek:

# .dev.vars — dotenv-formátum, .gitignore-ba VELE
NUXT_SESSION_PASSWORD=egy-legalabb-32-karakteres-fejlesztoi-jelszo
STRIPE_SECRET_KEY=sk_test_...
NUXT_OAUTH_GITHUB_CLIENT_SECRET=...

# környezetenként külön fájl
.dev.vars
.dev.vars.staging

18.6Szkriptek a Workeren kívül: getPlatformProxy()

Van egy egész munkakategória, ami nem a Workerben fut, mégis a bindingokra van szüksége: adatbázis-seedelés, egyszeri adatjavítás, migrációs eszközök, riportgenerálás. Ezekre a wrangler egy Node-ból hívható API-t ad, ami a háttérben ugyanazt a workerd-t indítja el.

// scripts/seed.ts — sima Node-szkript, mégis valódi bindingokkal
import { getPlatformProxy } from 'wrangler'

const { env, dispose } = await getPlatformProxy({
  configPath: './wrangler.jsonc',
  environment: 'staging',     // melyik env bindingjai
  persist: true,              // ugyanaz az állapot, mint a dev szerveré
})

await env.DB.prepare('INSERT INTO products (id, name) VALUES (?, ?)')
  .bind('p1', 'Bögre')
  .run()

await env.CACHE.put('feature:uj-checkout', 'on')

await dispose()          // FONTOS: leállítja a workerd folyamatot

18.7③ wrangler dev a .output-on

Ez az első fok, ahol a kódod valódi workerd-ben fut — ugyanabban a binárisban, ami élesben is. Cserébe elveszíted a HMR-t: minden változtatás után újra kell buildelni.

npx nuxt build && npx wrangler dev

Nem fejlesztésre való, hanem kapunak. Ezen a fokon bukik ki:

• a hiányzó vagy nem támogatott Node API (a nodejs_compat ellenére is van ilyen);
• a túl hosszú modul-scope inicializálás — az 1 másodperces indulási keret;
• a nem workerd-kompatibilis függőség, ami Node-ban vidáman elfutott;
• a process, __dirname és társaik használata, amit a dev szerver elnézett.

# hasznos kapcsolók ezen a fokon
npx wrangler dev --test-scheduled     # /__scheduled útvonal a cron-handlerhez
npx wrangler dev --log-level debug
npx wrangler dev --local              # minden távoli binding ideiglenes kikapcsolása
# futás közben: D billentyű → Chrome DevTools (16.8)

18.8④ Távoli bindingok: "remote": true

Ez a legfontosabb újdonság a lokális fejlesztésben, és sokan még nem tudnak róla. Eddig a választás így nézett ki: vagy minden lokálisan emulált (gyors, de hazudik), vagy az egész Worker felmegy a felhőbe (hű, de lassú). A távoli bindingokkal bindingonként dönthetsz.

// wrangler.jsonc — a kód lokálisan fut, EZ a binding élesre kapcsolódik
{
  "r2_buckets": [{
    "bucket_name": "bolt-media",
    "binding": "MEDIA",
    "remote": true
  }]
}

A lényeg: a Workered továbbra is lokálisan fut, csak az adott binding mögötti erőforrás változik lokális szimulációról valódira. Megmarad a gyors iteráció, de az adat és a viselkedés igazi.

A távoli bindingok környezetekkel kombinálva a helyes minta: ne az éles adatra kapcsolódj, hanem a stagingére.

{
  "env": {
    "staging": {
      "r2_buckets": [{
        "bucket_name": "bolt-media-staging",
        "binding": "MEDIA",
        "remote": true
      }]
    }
  }
}

npx wrangler dev -e staging   # lokális kód, staging-erőforrások

18.9A régi teljes távoli mód: wrangler dev --remote

Ez a távoli bindingoktól különálló, régebbi mechanizmus: az egész Workeredet feltölti a Cloudflare preview környezetébe, és ott futtatja. Semmi nem emulálódik, minden binding automatikusan távoli.

Egy Nuxt-appnál a --remote ritkán a helyes válasz — általában vagy a ③ fok (valódi workerd lokálisan), vagy az ⑤ fok (preview deploy) a jobb üzlet. Akkor jön szóba, ha kifejezetten hálózat-specifikus viselkedést vizsgálsz: a request.cf valódi mezőit, geolokációt, TLS-részleteket, vagy a Cloudflare-hálózat cache-viselkedését.

18.10Amiben a lokális környezet hazudik — a teljes lista

A 16.7-ben már láttál egy rövidebb változatot. Itt a teljes, mert ez a modul erről szól:

18.11Típusok: wrangler types

A bindingokat a TypeScript alapból nem ismeri. A wrangler ki tudja generálni őket a konfigból, és ezt érdemes a build-lánc részévé tenni, nem kézzel karbantartani:

npx wrangler types --env-interface CloudflareEnv
npx wrangler types --env staging --check   # CI: elavult-e a generált fájl

// package.json — hogy sose felejtsd el
"scripts": {
  "postinstall": "wrangler types && nuxt prepare",
  "typecheck": "wrangler types --check && nuxt typecheck"
}

18.12Egy működő napi workflow

Összerakva a modult, így néz ki egy Nuxt + Cloudflare projekt package.json-je úgy, hogy a hűségi létra minden foka egy paranccsal elérhető legyen:

{
  "scripts": {
    // ① napi munka
    "dev": "nuxt dev",

    // lokális adat
    "db:reset": "rm -rf .wrangler/state && npm run db:migrate && npm run db:seed",
    "db:migrate": "wrangler d1 execute bolt --file=./db/schema.sql --local",
    "db:seed": "tsx scripts/seed.ts",

    // ③ valódi workerd — kiadás előtti kapu
    "dev:worker": "nuxt build && wrangler dev",

    // ④ staging-erőforrásokkal, lokális kóddal
    "dev:staging": "nuxt build && wrangler dev -e staging",

    // mérés (15. modul) és típusok
    "check:size": "wrangler deploy --dry-run --outdir=.bundle",
    "check:startup": "wrangler check startup",
    "typecheck": "wrangler types --check && nuxt typecheck",

    // ⑤ preview deploy + füstteszt (16-17. modul)
    "deploy:preview": "nuxt build && wrangler versions upload --preview-alias dev"
  }
}

A ritmus, ami ebből adódik: napközben dev; a feature végén egyszer dev:worker, hogy a workerd-specifikus hibák még nálad derüljenek ki; PR előtt check:size és check:startup; a merge után pedig a CI viszi tovább az ⑤ fokra.

18.13Ellenőrizd magad