skip to content

Develop & Deploy

Wrangler is the CLI that configures, runs and deploys Workers, and the Vitest plugin runs tests inside workerd. Interviewers ask how a team ships safely from config to production.

on this pageshow

explore

questions

23

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 Wrangler 4, what does wrangler dev run on your machine by default, and how does wrangler dev --remote differ?

level: juniorimportance: must knowfreq 68%

basics

~20 s

By default wrangler dev runs the Worker locally in workerd, the production runtime, through the Miniflare simulator, with most bindings simulated on disk. wrangler dev --remote uploads the code to a temporary preview on Cloudflare's network, where every binding is real.

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 is the difference between a version and a deployment, and how does wrangler deploy differ from wrangler versions upload?

level: juniorimportance: should knowfreq 45%

basics

~20 s

A Cloudflare Workers version is an immutable snapshot of code, config and bindings; a deployment says which one or two versions serve traffic. wrangler deploy creates a version and serves it to all traffic; wrangler versions upload creates one with none.

open as a page

With Cloudflare's Workers Vitest plugin, how do you make tests run inside workerd with your Wrangler bindings, and how does a test call the Worker?

level: juniorimportance: should knowfreq 35%

basics

~10 s

Add cloudflareTest() from @cloudflare/vitest-plugin to the Vitest config's plugins with wrangler.configPath set, so test files run in workerd with the Worker's bindings. Tests import env and exports from cloudflare:workers and call exports.default.fetch().

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 Cloudflare Workers, how do you roll a high-traffic API Worker's new version out to 5%, then 50%, then 100% from CI?

level: middleimportance: should knowfreq 38%

basics

~10 s

Upload with wrangler versions upload, then run wrangler versions deploy NEW@5% STABLE@95%, then 50/50, then NEW@100%, authenticating CI with CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID and comparing versions through the version metadata binding.

open as a page

In Cloudflare Workers, how do Previews, Version URLs and Wrangler environments differ when a team wants to test a pull request before production?

level: middleimportance: should knowfreq 30%

basics

~20 s

Previews from wrangler preview are per-branch copies with their own bindings and are meant for pull requests. Version URLs run one uploaded version against production resources. Wrangler environments are separately named, long-lived Workers such as a staging stage.

open as a page

During wrangler dev, how does Wrangler load local secrets from .dev.vars and .env files, and which value wins when they overlap?

level: middleimportance: should knowfreq 48%

basics

~20 s

Wrangler reads .dev.vars beside the Wrangler file, or, only when no .dev.vars file applies, the .env files. Their values override the config's vars locally. A .dev.vars.<env> file replaces .dev.vars, while .env files for an environment merge.

open as a page

Where does Wrangler keep a Worker's local KV, D1, R2 and Durable Object data during wrangler dev, and how does --persist-to change it?

level: middleimportance: should knowfreq 42%

basics

~20 s

Local binding data lives in .wrangler/state next to the Wrangler configuration file and survives restarts. --persist-to moves it to another directory, and every Wrangler command that seeds or reads that data must be given the same --persist-to.

open as a page

With Cloudflare remote bindings, how does a Worker using KV, D1 and a Durable Object under wrangler dev also reach the real Workers AI binding?

level: middleimportance: should knowfreq 38%

basics

~20 s

Keep the Worker local and mark the AI binding remote: true; Workers AI has no local simulator, so its calls go to Cloudflare while KV, D1 and the Durable Object stay simulated. Other bindings opt in the same way; Durable Objects cannot.

open as a page

In the Workers Vitest plugin, how do you apply a D1 database's migrations before tests run, and why does it take two functions?

level: middleimportance: should knowfreq 22%

basics

~20 s

readD1Migrations() runs in Node.js in the Vitest config to read the .sql files; pass the result in as a test-only binding, then call applyD1Migrations(env.DB, migrations) from cloudflare:test in a setup file, inside workerd, before each test file.

open as a page

With the Workers Vitest plugin, how do you test a Durable Object counter's stored state and its alarm without waiting for real time?

level: middleimportance: should knowfreq 32%

basics

~10 s

Call the Durable Object through a stub as production code does, then use runInDurableObject(stub, (instance, state) => ...) to read state.storage directly, and runDurableObjectAlarm(stub) to run a scheduled alarm immediately.

open as a page

With the Workers Vitest plugin, how do you unit test a Worker's scheduled cleanup handler, including the work it hands to ctx.waitUntil()?

level: middleimportance: should knowfreq 30%

basics

~10 s

Import the Worker module and call worker.scheduled(controller, env, ctx) yourself, with a controller from createScheduledController() and a ctx from createExecutionContext() in cloudflare:test; await waitOnExecutionContext(ctx) before asserting, so waitUntil work has settled.

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

After a Cloudflare Worker release ran a D1 migration that renamed a column, the team runs wrangler rollback; what does it restore, and what can still break?

level: seniorimportance: should knowfreq 35%

basics

~20 s

wrangler rollback immediately serves an earlier Cloudflare Worker version to 100% of traffic but leaves bound resources alone, so old code meets the renamed D1 column and fails. Durable Object class changes and deleted bindings can block it entirely.

open as a page

During a 50% gradual deployment of a Cloudflare Worker serving a single-page app from static assets, some users get 404s for hashed JavaScript files; why, and what fixes it?

level: seniorimportance: should knowfreq 28%

basics

~20 s

A Cloudflare Workers split routes every request independently, so a page's HTML can come from one version and its hashed script from the other, which lacks that file. A stable Cloudflare-Workers-Version-Key header keeps each user on one version.

open as a page

A Cloudflare Worker passed every check under wrangler dev but misbehaves in production; which platform behaviours does local mode not reproduce?

level: seniorimportance: should knowfreq 40%

basics

~20 s

Local mode runs the real runtime but not the network around it: KV has no cross-location propagation delay, request.cf is one cached snapshot, configured limits such as cpu_ms are not enforced, and Cron Triggers never fire on their own.

open as a page

With @cloudflare/vitest-plugin, a Durable Object counter test passes alone but fails after another test in its file, and adding reset() causes 'no such table' D1 errors. Why?

level: seniorimportance: should knowfreq 20%

basics

~20 s

The plugin isolates storage per test file, not per test, so a counter named "home" keeps the earlier test's increments. reset() deletes all data from every binding, including the D1 tables migrations created, so later tests need the migrations re-applied.

open as a page

How do the Cloudflare Vite plugin and wrangler's getPlatformProxy() differ in giving a framework's local dev server access to Workers bindings?

level: middleimportance: nice to knowfreq 25%

basics

~20 s

The Cloudflare Vite plugin runs the Worker's code itself inside workerd during vite dev, with real bindings APIs. getPlatformProxy() leaves the code in Node.js and hands it env, cf, ctx and caches proxied to a local workerd, without running the Worker.

open as a page

As the lead for a high-traffic Cloudflare Workers API, how would you set the team's gradual deployment policy: starting percentage, promotion gates, rollback ownership and exceptions?

level: principalimportance: nice to knowfreq 25%

basics

~20 s

Make uploads the default and releases a gated step: 0% with override smoke tests, then a small percentage held until per-version metrics are stable. Let on-call roll back freely, and ship Durable Object class and container changes alone with wrangler deploy.

open as a page

As the lead for a Workers codebase, how do you decide what the team tests in the Workers Vitest plugin and what it checks only against a production build or remote resources?

level: principalimportance: nice to knowfreq 15%

basics

~20 s

Use the plugin for handler logic and binding behaviour, since it is fast, local and credential-free. Cover what its runner changes, such as compatibility flags and module resolution, with a production-build check like createTestHarness(), and platform-only behaviour on a deployed preview.

open as a page