Fejlesztői workflow: wrangler, lokális dev, tesztelés, debug

11.1A napi hurok — mi változik a Beanstalk-rutinhoz képest

A legfontosabb strukturális változás: a lokális futtatás nem szimuláció, hanem ugyanaz a runtime. A wrangler dev a workerd-t (a Workers nyílt forráskódú futtatókörnyezetét) indítja el a gépeden, Miniflare-be csomagolva, a bindingok lokális megfelelőivel. Ez az, amiért a „lokálisan ment, élesben nem" osztály nagyrészt eltűnik.

11.2Wrangler: az egy CLI, ami a fél AWS-konzolt kiváltja

A wrangler egyszerre tölti be az eb, a aws CLI, a terraform és részben a psql/s3cmd szerepét. Érdemes kategóriákban a fejedben tartani:

Projekt és fejlesztés

npm create cloudflare@latest        # új projekt (C3), keretrendszer-sablonokkal
npx wrangler dev                    # lokális dev szerver (workerd)
npx wrangler dev --env staging      # nevesített környezet konfigjával
npx wrangler dev --test-scheduled   # cron-teszteléshez /__scheduled route
npx wrangler dev --tunnel           # lokális szerver megosztása Tunnelen (webhook-teszt!)
npx wrangler types                  # Env típus generálása a bindingokból

Deploy és release (8. modul)

npx wrangler deploy --env production
npx wrangler versions upload        # feltöltés forgalom nélkül
npx wrangler versions deploy        # forgalomarány állítása (kanári)
npx wrangler rollback
npx wrangler deployments list       # mi fut most, mióta

Erőforrások — ez váltja ki az AWS-konzolt

# létrehozás (a 8. modul env-fegyelme szerint -staging / -prod párokban)
npx wrangler d1 create app-prod --location weur
npx wrangler r2 bucket create uploads-prod
npx wrangler kv namespace create CONFIG
npx wrangler queues create jobs

# adatműveletek
npx wrangler d1 execute app-prod --remote --command "SELECT COUNT(*) FROM users" --json
npx wrangler d1 migrations apply app-prod --remote
npx wrangler d1 export app-prod --remote --output=./dump.sql
npx wrangler r2 object put uploads-prod/logo.png --file ./logo.png
npx wrangler kv key put --binding CONFIG feature-flags '{"beta":true}' --remote

# titkok (8. modul)
npx wrangler secret put STRIPE_KEY --env production
npx wrangler secret list --env production

Megfigyelés és hibakeresés (9. modul)

npx wrangler tail --env production --status error
npx wrangler tail --format json | jq '.logs[].message'

11.3Lokális fejlesztés: hol él az állapot?

A wrangler dev minden bindingnak lokális megfelelőt ad: a D1 egy valódi SQLite-fájl, az R2 és a KV a lemezre írnak, a Queues és a Durable Objects lokálisan futnak. Az állapot alapértelmezetten a .wrangler/state mappában perzisztálódik (tehát túléli az újraindítást — és a .gitignore-ba való).

# saját állapot-mappa (pl. több feature-branch külön adattal)
npx wrangler dev --persist-to .state/feature-x

# FONTOS: a lokális adatot módosító parancsoknál is meg kell adni
npx wrangler d1 execute app-dev --local --persist-to .state/feature-x --file=./seed.sql
npx wrangler kv key put --binding CONFIG test 12345 --local --persist-to .state/feature-x

A lokális adat feltöltése (seed) ugyanígy megy: egy seed.sql a repóban, és egy npm run db:seed script — az új fejlesztőnek így a klónozás után két parancs a működő környezet. Ez a Beanstalk-világ „kérj hozzáférést a dev RDS-hez" rituáléjának a helyére lép.

11.4Remote bindings — a legjobb újítás a napi munkában

Régen két rossz választásod volt: vagy minden lokálisan szimulált (gyors, de az adat nem valódi), vagy wrangler dev --remote, ahol az egész Worker a felhőben fut (valódi, de lassú iteráció). A mai megoldás a kettő legjobbja: a kód lokálisan fut, de bindingonként megmondhatod, hogy az adott erőforrás az éles legyen:

{
  "r2_buckets": [{
    "binding": "UPLOADS",
    "bucket_name": "uploads-staging",
    "remote": true            // ez a binding az ÉLES (staging) bucketre megy
  }],
  "d1_databases": [{
    "binding": "DB", "database_name": "app-dev", "database_id": "…"
    // remote nincs megadva → lokális SQLite, gyors és eldobható
  }]
}

Tipikus használat: a lokális D1-en dolgozol (gyors, szabadon törölhető), de az R2-bindinget vagy egy külső AI/Vectorize szolgáltatást a valódira kötöd, mert azt nem lehet értelmesen szimulálni. A wrangler dev --local flaggel egy pillanat alatt kikapcsolod az összes remote bindinget (pl. repülőn).

11.5Típusok: a bindingjaid legyenek típusosak

A wrangler types a konfigodból generálja az Env típust — vagyis az env.DB, env.UPLOADS, env.STRIPE_KEY mind típusos lesz, és a hiányzó binding fordítási hiba, nem éjszakai riasztás:

npx wrangler types            # → worker-configuration.d.ts

Tedd be a package.json-ba a postinstall-ba vagy a dev-script elé, hogy soha ne csússzon el a konfigtól. Nuxt-projektben (3. modul) ezután deklaráld a H3EventContext-en, hogy az event.context.cloudflare.env is típusos legyen — így a server route-jaidban is IDE-támogatást kapsz.

11.6Tesztelés: a tesztjeid a Workers-runtime-ban futnak

Ez a rész az, ami Node-háttérrel a legkellemesebb meglepetés. A hivatalos ajánlás a Vitest-integráció (@cloudflare/vitest-pool-workers): a teszt-fájljaid nem Node-ban, hanem a workerd-ben futnak, így közvetlenül elérik a bindingokat és a runtime API-kat — nincs több „mockoljuk az S3-klienst" kör.

import { cloudflareTest } from "@cloudflare/vitest-pool-workers";
import { defineConfig } from "vitest/config";

export default defineConfig({
  plugins: [cloudflareTest({ wrangler: { configPath: "./wrangler.jsonc" } })],
});

1. példa: unit teszt valódi bindinggal

import { env } from "cloudflare:workers";
import { it, expect } from "vitest";
import { createInvoice } from "../src/invoices";

it("számlát ír a D1-be", async () => {
  await createInvoice(env, { tenantId: "acme", total: 1000 });

  // közvetlenül ellenőrizzük a binding állapotát — nincs mock!
  const row = await env.DB
    .prepare("SELECT total FROM invoices WHERE tenant_id = ?")
    .bind("acme").first();
  expect(row.total).toBe(1000);
});

A tárolás teszt-fájlonként izolált, tehát a tesztek nem szemetelnek egymásnak — ez az, amit Node-világban külön tranzakció-rollback trükkökkel értél el.

2. példa: a teljes Worker meghívása (integrációs jelleggel)

import { exports } from "cloudflare:workers";
import "../src/index";

it("404-et ad ismeretlen útvonalra", async () => {
  const res = await exports.default.fetch("http://example.com/nincs-ilyen");
  expect(res.status).toBe(404);
});

3. példa: Durable Object tesztelése — a különleges eszközök

A DO-k (7. modul) tesztelésére saját segédfüggvények vannak, amikkel a belsejükbe nyúlhatsz és az időt is „előretekerheted":

import { env } from "cloudflare:workers";
import { runInDurableObject, runDurableObjectAlarm, evictDurableObject }
  from "cloudflare:test";

it("lejáró foglalást felszabadít az alarm", async () => {
  const stub = env.EVENT_SEATS.get(env.EVENT_SEATS.idFromName("gala"));
  await stub.reserve("user-1", 2);

  // belenézünk az objektum saját tárába
  await runInDurableObject(stub, async (instance, state) => {
    const free = state.storage.sql.exec("SELECT free FROM seats").one().free;
    expect(free).toBe(98);
  });

  await runDurableObjectAlarm(stub);   // nem várunk 10 percet — most lefuttatjuk
  await evictDurableObject(stub);      // szimulált kilakoltatás: túléli a memória-vesztést?
});

11.7Debug: breakpointok, profil, élő log

• Breakpointok: a wrangler dev DevTools-t nyit (a terminálban kiírt d billentyűvel vagy a megadott URL-en) — valódi breakpoint, step, watch a Worker-kódodban, ugyanúgy, ahogy a Node-inspectorral szoktad.
• CPU-profil: a DevTools profilozója megmutatja, mi eszi a CPU-ms-t — ez az eszköz a 2. és 9. modul CPU-limit problémáira. Ha egy endpoint gyanúsan drága, itt derül ki, hogy egy JSON-parse vagy egy kriptós ciklus a bűnös.
• Élő log: wrangler tail — élesből, szűrhetően (--status error, --search "tenantId").
• Webhookok tesztelése: wrangler dev --tunnel — a lokális dev szervered kap egy publikus Cloudflare Tunnel URL-t, amit beírhatsz a Stripe/GitHub webhook-beállításába. Nincs többé ngrok-tánc.
• Startup-idő: ha a Worker indulása lassul (1 s-os limit, 2. modul), a wrangler startup-profilozója megmutatja, melyik import a nehéz.

11.8Több Worker, monorepo, service bindings

Ahogy nő a rendszer, jellemzően szétválik: a fő Nuxt-app Worker, mellette egy-két háttér-Worker (queue-consumer, cron, admin-API). A szervezés eszközei:

• Külön Worker = külön wrangler-konfig egy-egy mappában (pnpm/npm workspace). A Workers Buildsben a Root directory beállítás mutat az almappára (8. modul).
• Service bindings a Workerek közti hívásra: nem az interneten át mennek, hanem belső hívásként — így a köztük lévő kommunikáció gyors, és nem kell hitelesítést kitalálni. Egy env.ADMIN_API.fetch(...) vagy RPC-metódushívás.
• Közös kód egy packages/shared csomagban (típusok, validátorok, D1-séma) — mivel minden TypeScript, ez a rész a megszokott monorepo-tudásod.
• A Vitest-integráció több Workeres projekteket is támogat, tehát a service bindinges hívásláncot is tudod tesztelni.

11.9Csapat: onboarding, hozzáférés, IaC

Egy új fejlesztő első napja

1. git clone + npm i
2. npx wrangler login (böngészős OAuth — nincs kulcs-csereberélés)
3. .dev.vars kitöltése a csapat titkos-tárából (a secrets.required lista megmondja, mi kell — 8. modul)
4. npm run db:seed → npm run dev — és fut a teljes stack lokálisan

Ehhez nem kell AWS-konzol-hozzáférés, VPN, dev-RDS jelszó vagy IAM-szerepkör. Az élesre írási jogot pedig a Cloudflare API-token szintjén szabod (a tokenek hatóköre szűkíthető: csak Workers, csak egy zóna, csak olvasás).

Infrastructure as Code — mikor éri meg?

A wrangler-konfig maga már IaC: a bindingok, route-ok, cron-ok, limitek a repóban vannak és verziózottak. Ami nincs benne: maguknak az erőforrásoknak a létrehozása (D1, bucket, queue — 8. modul). Kis-közepes csapatnál ez néhány dokumentált parancs, és ez teljesen elég. Terraformot akkor húzz be, ha több fiókod/környezeted van, auditálható erőforrás-életciklus kell, vagy a Cloudflare-en kívüli infrád is Terraformmal megy — a provider támogatja a Workerst, assetekkel együtt. Van emellett automatic provisioning is: a wrangler deploykor felajánlja a hiányzó erőforrások létrehozását — kényelmes fejlesztéshez, de éles környezetben inkább explicit legyen minden.

11.10Napi menü — cheatsheet

11.11Ellenőrizd magad