A wrangler konfigurációs fájl: teljes referencia

12.1Mi ez a fájl, mi a neve, hol van?

A neve wrangler.jsonc (vagy wrangler.json, vagy a régebbi wrangler.toml) — a Wrangler v3.91 óta mindhárom formátum támogatott, és új projekthez a Cloudflare a wrangler.jsonc-t ajánlja (néhány újabb funkció csak JSON-konfiggal érhető el). A tartalom mindháromban ugyanaz, csak a szintaxis más — a .jsonc előnye, hogy kommentelhető, ami egy ilyen fájlnál sokat ér.

Hol van? A projekt gyökerében, a package.json mellett. A Wrangler az aktuális könyvtárból indulva felfelé keresi. Monorepóban minden Worker-csomag saját mappájában van egy-egy konfig; ilyenkor vagy a csomag mappájából futtatod a parancsot, vagy megadod: wrangler deploy --config apps/api/wrangler.jsonc (a Workers Buildsben ugyanezt a Root directory beállítás oldja meg — 8. modul).

Az első sor mindig ez legyen — ettől kapsz automatikus kiegészítést és validációt a szerkesztődben (VS Code, WebStorm), tehát nem kell fejből tudnod a mezőneveket:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  …
}

12.2Az anatómia: hat réteg

Bármilyen hosszú is egy konfig, mindig ugyanaz a hat dolog van benne. Ha ezt a hatot a fejedben tartod, bármelyik példát el tudod olvasni:

12.3Teljes, kommentált példa — a te stackedhez

Ez egy éles jellegű konfig egy Nuxt-alapú, multitenant SaaS-hoz, amiben szinte minden szerepel, amiről a kurzus szólt. Használd sablonként:

{
  "$schema": "./node_modules/wrangler/config-schema.json",

  /* ---------- ① IDENTITÁS ÉS BELÉPÉSI PONT ---------- */
  "name": "my-app",                          // a Worker neve (a dashboardon is ez)
  "main": "./.output/server/index.mjs",      // a belépési modul (Nuxt/Nitro build kimenete)
  "assets": {                                 // statikus fájlok (3. modul)
    "directory": "./.output/public",
    "binding": "ASSETS",                      // env.ASSETS.fetch(...) a kódban
    "not_found_handling": "single-page-application",
    "run_worker_first": ["/api/*"]           // ezekre a Worker fut előbb
  },

  /* ---------- ② RUNTIME-VISELKEDÉS (2. modul) ---------- */
  "compatibility_date": "2026-08-02",        // a runtime "verziója" — nem változik alattad
  "compatibility_flags": ["nodejs_compat"],  // Node API-k engedélyezése

  /* ---------- ③ HOL ÉRHETŐ EL ---------- */
  "workers_dev": false,                      // ne legyen *.workers.dev cím élesben
  "preview_urls": true,                      // PR-preview URL-ek (8. modul)
  // routes: melyik domainen fut — env-enként adjuk meg lentebb

  /* ---------- ④ BINDINGS — MIHEZ FÉR HOZZÁ ---------- */
  // (itt csak a közös alapok; a környezetfüggőket az env blokkokban)
  "vars": {                                    // NEM titkos konfig (a repóban van!)
    "APP_NAME": "MyApp",
    "SUPPORT_EMAIL": "help@example.com"
  },

  "durable_objects": {                         // 7. modul
    "bindings": [
      { "name": "RATE_LIMITER", "class_name": "RateLimiter" }
    ]
  },
  "migrations": [                              // DO-osztályok életciklusa (nem D1!)
    { "tag": "v1", "new_sqlite_classes": ["RateLimiter"] }
  ],

  "workflows": [                               // 7. modul
    { "name": "onboard-tenant", "binding": "ONBOARD",
      "class_name": "OnboardTenant" }
  ],

  /* ---------- ⑤ PLATFORM-BEÁLLÍTÁSOK ---------- */
  "triggers": { "crons": ["0 1 * * *"] },      // UTC! (7. modul)
  "limits": { "cpu_ms": 60000 },              // önvédelem (2. modul)
  "observability": { "enabled": true },        // 9. modul
  "upload_source_maps": true,               // olvasható stack trace-ek

  /* ---------- ⑥ KÖRNYEZETEK (8. modul) ---------- */
  "env": {
    "staging": {
      "name": "my-app-staging",
      "routes": [{ "pattern": "staging.example.com/*",
                   "zone_name": "example.com" }],

      // FIGYELEM: ha egy nem-öröklődő kulcsot itt megadsz,
      // MINDET meg kell adnod ebben a blokkban (12.5)!
      "vars": { "APP_NAME": "MyApp (staging)", "SUPPORT_EMAIL": "help@example.com" },
      "d1_databases": [{ "binding": "DB", "database_name": "app-staging",
                          "database_id": "<STAGING_UUID>" }],
      "r2_buckets": [{ "binding": "UPLOADS", "bucket_name": "uploads-staging" }],
      "kv_namespaces": [{ "binding": "CONFIG", "id": "<STAGING_KV_ID>" }],
      "queues": {
        "producers": [{ "binding": "JOBS", "queue": "jobs-staging" }],
        "consumers": [{ "queue": "jobs-staging", "max_batch_size": 10,
                        "dead_letter_queue": "jobs-staging-dlq" }]
      },
      "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<STAGING_HD_ID>" }],
      "durable_objects": { "bindings": [
        { "name": "RATE_LIMITER", "class_name": "RateLimiter" } ] },
      "workflows": [{ "name": "onboard-tenant-staging", "binding": "ONBOARD",
                      "class_name": "OnboardTenant" }],
      "observability": { "enabled": true, "head_sampling_rate": 1 }
    },

    "production": {
      "name": "my-app-production",
      "routes": [{ "pattern": "app.example.com/*",
                   "zone_name": "example.com" }],
      "vars": { "APP_NAME": "MyApp", "SUPPORT_EMAIL": "help@example.com" },
      "d1_databases": [{ "binding": "DB", "database_name": "app-prod",
                          "database_id": "<PROD_UUID>" }],
      "r2_buckets": [{ "binding": "UPLOADS", "bucket_name": "uploads-prod" }],
      "kv_namespaces": [{ "binding": "CONFIG", "id": "<PROD_KV_ID>" }],
      "queues": {
        "producers": [{ "binding": "JOBS", "queue": "jobs-prod" }],
        "consumers": [{ "queue": "jobs-prod", "max_batch_size": 50,
                        "max_retries": 5, "dead_letter_queue": "jobs-prod-dlq" }]
      },
      "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<PROD_HD_ID>" }],
      "durable_objects": { "bindings": [
        { "name": "RATE_LIMITER", "class_name": "RateLimiter" } ] },
      "workflows": [{ "name": "onboard-tenant", "binding": "ONBOARD",
                      "class_name": "OnboardTenant" }],
      "observability": { "enabled": true, "head_sampling_rate": 0.1 }
    }
  }
}

12.4Mezőreferencia kategóriánként

Alap / identitás

Elérhetőség / routing

Bindings — az erőforrások

Platform-viselkedés

12.5Az öröklődés pontos szabálya (ezt érdemes megjegyezni)

A 8. modulban röviden úgy fogalmaztunk, hogy „a bindingok nem öröklődnek". A pontos szabály ennél egy árnyalattal finomabb, és pont ez az árnyalat okozza a hibákat:

• Öröklődő (inheritable) kulcsok: main, compatibility_date, compatibility_flags, limits, triggers, observability, assets, workers_dev, preview_urls stb. Ezeket elég a top-levelen megadni; az env-ek megkapják, és felül is írhatják őket.
• Nem öröklődő (non-inheritable) kulcsok: minden binding — vars, d1_databases, r2_buckets, kv_namespaces, queues, hyperdrive, durable_objects, workflows, services, ai…

És a szabály, ami mindenkit megvisel egyszer: ha egy nevesített környezetben akár egyetlen nem öröklődő kulcsot felülírsz, akkor az összes többi nem öröklődő kulcsot is meg kell adnod ugyanabban a blokkban. Nincs részleges öröklés.

// ❌ HIBÁS — lokálisan még működik, deploykor validációs hibát dob:
{
  "kv_namespaces": [{ "binding": "CONFIG", "id": "<ID>" }],
  "vars": { "API_KEY": "dev" },
  "env": {
    "production": {
      "vars": { "API_KEY": "prod" }     // felülírtunk EGY non-inheritable kulcsot…
      // …ezért a kv_namespaces-t is KÖTELEZŐ itt megadni!
    }
  }
}

// ✅ HELYES — minden non-inheritable kulcs szerepel az env-ben:
{
  "env": {
    "production": {
      "vars": { "API_KEY": "prod" },
      "kv_namespaces": [{ "binding": "CONFIG", "id": "<PROD_ID>" }]
    }
  }
}

Ezért néz ki a 12.3-as példa „redundánsnak": a staging és a production blokkban minden binding újra szerepel. Ez nem hanyagság, hanem a modell — és egyben védelem: így nem fordulhat elő, hogy a staging egy kifelejtett sor miatt csendben a production adatbázisára mutat.

12.6Mi NEM kerül ebbe a fájlba?

A database_id, kv id, hyperdrive id viszont nyugodtan mehet a repóba — ezek azonosítók, nem hitelesítő adatok: önmagukban nem adnak hozzáférést, csak a fiókodon belül, hitelesített kontextusban értelmesek.

12.7Gyakori hibák — gyorsdiagnózis

12.8Ellenőrizd magad