Declaration files

Four JSON files in app/ provision real infrastructure when you deploy. Each one declares what should exist; the platform diffs that against what does exist and reconciles the difference.

Which file do I need?

app/durable-objects.json

{
  "classes": [{ "binding": "CHAT_ROOM", "class": "ChatRoom" }],
  "confirmDelete": ["OldClass"]
}

The class must be exported from your worker bundle or the deploy fails with a clear error — that check exists so a declared-but-missing class can't ship as a broken binding. The platform registers it with a SQLite-backed migration. Full guide: Durable Objects.

app/queues.json

{
  "queues": [
    {
      "name": "orders",
      "maxConcurrency": 5,
      "maxRetries": 5,
      "backoff": { "baseSeconds": 10, "maxSeconds": 3600 },
      "target": { "kind": "handler" }
    }
  ]
}

Provisioning creates the queue and a dead-letter twin. Full guide: Queues.

app/search.json

The richest of the four — it provisions a managed AI Search instance for meaning-based retrieval.

{
  "instances": [
    {
      "name": "docs",
      "source": "assets",
      "prefix": "search/docs/",
      "index": "hybrid",
      "tokenizer": "porter",
      "syncIntervalSeconds": 3600,
      "metadata": [{ "field": "category", "type": "text" }]
    }
  ]
}

Two limits worth designing around: five metadata facets per instance is a hard cap, and retrieval returns a bounded candidate set. AI Search nominates and re-ranks; your database still owns facet counts, sorting and pagination. Building a faceted product listing on the index alone produces counts that are wrong.

app/email.json

{ "senders": [{ "name": "default", "displayName": "Acme Shop" }] }

The address is deterministic per app, environment and sender, so each environment gets its own automatically. Full guide: Transactional email.

Desired state, and the delete guard

This is the semantic that matters most, and it's the same for all four files:

Each file is the complete desired set for the environment being deployed. The platform diffs it against what exists and reconciles.

Which raises the obvious risk — remove a line, lose the data behind it. So removals are guarded:

To remove something, name it in the same file:

{
  "classes": [{ "binding": "CHAT_ROOM", "class": "ChatRoom" }],
  "confirmDelete": ["AbandonedRoom"]
}

Two behaviours follow that are worth internalising:

• An absent file means "keep what exists", never "delete everything". That's deliberate partial-deploy safety: a deploy from a tree where the file didn't sync can't wipe your infrastructure.
• Renaming is delete-plus-create. Storage does not follow a name. Renaming a Durable Object class abandons its rooms; renaming a queue abandons its backlog. Renaming only a binding, with the class or name unchanged, is free.

search.json additionally has confirmRecreate, because some field changes are immutable and force a rebuild of the index rather than an in-place edit.

wrangler.toml is not read

The single most common configuration mistake here:

Deploys never read wrangler.toml. It exists so local tooling works. A [[durable_objects]] or [[queues]] section in it does nothing.

The platform now catches this rather than silently ignoring it — declare queues there and the deploy fails with:

Error: wrangler.toml declares queues, but Spike deploys do not read
wrangler.toml. Declare them in app/queues.json instead, e.g.
{"queues":[{"name":"orders","maxConcurrency":5}]} — the platform
provisions queue + DLQ and binds env.QUEUE_ORDERS on deploy.

Configuration that isn't one of these files

For completeness, since "what config can an app have?" has a wider answer:

And things that are not files at all — worker secrets, custom domains, the firewall, analytics opt-in and per-app cache config are managed through the CLI or console rather than declared in the tree. See Domains and secrets.

Next

• App anatomy — where these sit in the project tree.
• Build and deploy — how reconciliation appears in the deployment event stream.
• Environments — why each environment gets its own resources.