skip to content

Wrangler Config Files

A wrangler.jsonc or wrangler.toml file declares a Worker's entry point, date, bindings, routes and environments. Interviewers ask why bindings must be repeated in each environment.

on this pageshow

explore

questions

5

In Cloudflare Workers, what must a Wrangler configuration file declare, and why does Cloudflare recommend wrangler.jsonc over wrangler.toml for new projects?

level: juniorimportance: must knowfreq 55%

answer

  1. three required keys
  2. entry module and a runtime date
  3. same keys, different syntax
  4. Wrangler edits JSON configs for you

basics

~20 s

A Wrangler file needs at least name, main and compatibility_date. JSONC and TOML carry identical keys, but Cloudflare recommends wrangler.jsonc because some newer Wrangler features, such as writing a newly created binding into the file, work only with JSON configs.

solid answer

~40 s

To deploy a Worker with code, the file needs `name`, `main` (the entry module) and `compatibility_date`; routes, triggers, limits and bindings are optional. Since Wrangler 3.91.0 the same keys can be written as `wrangler.jsonc`/`wrangler.json` or `wrangler.toml`, and only the syntax differs. Cloudflare recommends JSONC for new projects because some newer Wrangler features target JSON configs: after a command such as `wrangler kv namespace create`, Wrangler offers to add the binding to a JSON file itself but only prints a snippet for TOML. A `$schema` line pointing at `node_modules/wrangler/config-schema.json` gives editors autocomplete and validation. If both formats sit in one folder, Wrangler reads the JSON file and silently ignores the TOML one.

code

json · 6 lines
json
{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "orders-api",
  "main": "src/index.js",
  "compatibility_date": "2026-10-01"
}

go deeper

for a junior

Recall the three required keys, name, main and compatibility_date, and that the file may be JSONC or TOML with the same keys inside.

for a middle

Explain the lookup order, wrangler.json then wrangler.jsonc then wrangler.toml, the --config override, and what the $schema line does for editors.

for a senior

Point out the operational traps: a stale TOML file beside a JSONC one, and TOML projects missing Wrangler's automatic binding write-back.

for a principal

Set a team default of one JSONC file per Worker, with environments inside it, so reviews and tooling see a single source of truth.

## What the Wrangler file is A **Wrangler configuration file** is the file Wrangler, Cloudflare's command-line tool for Workers, reads before `wrangler dev`, `wrangler deploy` and most other commands. It says which code to bundle, what the Worker is called on the account, which runtime behaviour to pin, which resources appear on `env`, and how traffic reaches the Worker. Cloudflare's documentation recommends treating this file as the **source of truth** for a Worker's configuration instead of changing the same settings in the dashboard, because the next deploy from the file overwrites most dashboard edits. ## The keys every deployable Worker needs At a minimum, three keys are required to deploy a Worker that has code: - `name` is the Worker's name on the account. Use lowercase letters, digits and dashes; the documentation says not to use underscores. A name can run to 255 characters, but a Worker that uses a `workers.dev` subdomain is limited to 63 and cannot start or end with a dash. - `main` is the path to the entry module, such as `src/index.js`, the ES module whose `export default { fetch }` handles requests. It may be left out only for an assets-only Worker. - `compatibility_date` is a `yyyy-mm-dd` date that pins which runtime behaviour the Worker gets. What each date switches on is a subject of its own, covered in the lesson on compatibility dates. Without a `compatibility_date`, `wrangler deploy` stops and asks you to add one to the file or pass `--compatibility-date`. Everything else is optional: `account_id` (which can also come from the `CLOUDFLARE_ACCOUNT_ID` environment variable), routes, Cron Triggers, limits, placement and every binding. ## JSONC versus TOML Since Wrangler 3.91.0 the file may be written as JSON (`wrangler.json` or `wrangler.jsonc`) or as TOML (`wrangler.toml`). Before that release only TOML existed, which is why older projects and tutorials still use it. | | `wrangler.jsonc` / `wrangler.json` | `wrangler.toml` | |---|---|---| | Syntax | JSON objects; the `.jsonc` form allows comments | TOML tables such as `[env.staging]` | | Keys and meaning | identical | identical | | Cloudflare's advice | recommended for new projects | still supported | | Wrangler adding a binding it just created | offers to write it into the file | prints a snippet for you to paste | The key set is the same in both, so converting a file changes syntax only. A TOML table such as `[env.staging]` becomes an `"env": { "staging": { } }` object, and a TOML array of tables such as `[[kv_namespaces]]` becomes a JSON array of objects under `"kv_namespaces"`. Values, defaults and inheritance rules do not change, so a Worker deployed from either file behaves the same. The practical difference is tooling. Cloudflare says some newer Wrangler features are available only to JSON configs. One concrete case: after a resource-creating command such as `wrangler kv namespace create`, Wrangler offers to add the new binding to a JSON config itself (or does it without asking when given `--update-config`), but for a TOML file it only prints the snippet. ## How Wrangler finds the file 1. A path passed with `--config` (short form `-c`) always wins. 2. Otherwise Wrangler looks for `wrangler.json`, then `wrangler.jsonc`, then `wrangler.toml`, starting in the current directory (or the one given with `--cwd`) and walking up through parent directories. 3. When two formats sit side by side, the JSON one is used and the TOML one is ignored without a warning. A stale `wrangler.toml` left behind after a migration therefore misleads readers, not Wrangler. Build tools and framework plugins can also write a `.wrangler/deploy/config.json` file whose `configPath` redirects `wrangler deploy`, `wrangler dev` and `wrangler versions upload` to a generated configuration. Wrangler prints a message when it follows such a redirect. ## The `$schema` line New JSONC files usually start with `"$schema": "./node_modules/wrangler/config-schema.json"`. The Wrangler package ships that JSON Schema file, and editors use it for autocomplete and to flag misspelt or misplaced keys while you type. It does not pin a Wrangler version, change a deploy or load extra settings. ## Practical rules - Start new projects with `wrangler.jsonc` and the `$schema` line. - Keep one file per Worker and express staging and production as environments inside it, not as copied files. - Delete the old `wrangler.toml` when you convert, so nobody edits the file Wrangler no longer reads. - Commit the file, and make configuration changes there rather than in the dashboard. - Keep account IDs out of shared templates when several accounts deploy the same code; `CLOUDFLARE_ACCOUNT_ID` in the CI environment supplies `account_id` instead. - Use comments in the JSONC file to explain non-obvious choices, such as why a route exists, since reviewers read this file more often than the dashboard.

  • How do you point Wrangler at a configuration file that is not in the default location?
    Pass `--config` (or `-c`) with the path on any command, for example `wrangler deploy -c ./workers/orders/wrangler.jsonc`. Build tools can instead write `.wrangler/deploy/config.json` containing a `configPath`; `wrangler deploy`, `wrangler dev` and `wrangler versions upload` then follow that redirect to a generated file, and Wrangler says so in its output. A generated file should not contain environments.
  • What changes for the Worker if a team converts wrangler.toml to wrangler.jsonc?
    Nothing about how it deploys: both formats map to the same keys, so `[env.staging]` becomes an `env.staging` object and the values carry over. What changes is tooling: editors validate against the `$schema`, and Wrangler can write newly created bindings into the file. The old TOML file should be deleted, because Wrangler would read the JSON one and ignore it anyway.

  • Wrangler 4 reads only wrangler.toml, so JSON config files need a converter
  • wrangler.jsonc and wrangler.toml support different sets of configuration keys
  • account_id must be written in the file before any deploy can run
  • The $schema line pins which Wrangler version deploys the Worker
  • With both files present, Wrangler merges wrangler.toml into wrangler.jsonc

Assumes Wrangler 4 (4.149.0); JSON config files have been accepted since Wrangler 3.91.0, before which only wrangler.toml existed.

open as a page

In a Wrangler configuration file, which keys does an env block inherit from the top level, and why must vars and bindings be repeated?

level: middleimportance: must knowfreq 45%

basics

~20 s

An env block inherits most keys, such as main, compatibility_date, routes, triggers and limits, and its Worker is named name-env. Vars, define and every binding are not inherited, so a block that omits them gets none, and Wrangler only warns.

open as a page

In Cloudflare Workers, what happens on the next wrangler deploy to vars, routes and secrets someone changed in the dashboard instead of the Wrangler file?

level: middleimportance: should knowfreq 25%

basics

~20 s

wrangler deploy deletes dashboard vars the file does not list unless keep_vars or --keep-vars is set, replaces routes with the file's list when it has any, and always keeps secrets until wrangler secret delete removes them.

open as a page

In Cloudflare Workers, how do routes, Custom Domains and the workers.dev subdomain differ when a Wrangler file attaches a Worker to traffic?

level: middleimportance: should knowfreq 40%

basics

~20 s

A route runs a Worker on matching URL patterns of a proxied hostname, in front of an origin. A Custom Domain makes the Worker the origin of a whole hostname, with Cloudflare creating DNS and certificate. workers.dev is the account's test subdomain.

open as a page

In Wrangler, why does production break when CI runs wrangler deploy --env staging on a file whose top level holds production's custom domain, KV namespace and Cron Trigger?

level: seniorimportance: should knowfreq 30%

basics

~20 s

Staging inherited routes and triggers but not the KV binding, so the deploy moved api.example.com to a staging Worker whose env.CACHE is undefined, and doubled the cron. In CI Wrangler repoints an existing Custom Domain without asking.

open as a page