In Cloudflare Workers, what must a Wrangler configuration file declare, and why does Cloudflare recommend wrangler.jsonc over wrangler.toml for new projects?
answer
- three required keys
- entry module and a runtime date
- same keys, different syntax
- Wrangler edits JSON configs for you
basics
~20 sA 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 sTo 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{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "orders-api",
"main": "src/index.js",
"compatibility_date": "2026-10-01"
}go deeper
Recall the three required keys, name, main and compatibility_date, and that the file may be JSONC or TOML with the same keys inside.
Explain the lookup order, wrangler.json then wrangler.jsonc then wrangler.toml, the --config override, and what the $schema line does for editors.
Point out the operational traps: a stale TOML file beside a JSONC one, and TOML projects missing Wrangler's automatic binding write-back.
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.