wrangler preview configures containers for preview deployments

Introduced 2026-08-20 · score 0.98

HOW TO USE IT

When a Worker preview needs a Durable Object backed by a container, declare it under `previews.containers` with its `class_name`, then run `npx wrangler preview` to build and deploy the image. Use `npx wrangler preview --json` from a non-interactive shell for machine-readable output; the release note recommends a prebuilt image over a Dockerfile.

WHY THIS HELPS

Configure a Worker preview deployment to run a Durable Object backed by a container.

REQUIREMENTS AND LIMITATIONS

• Version: 4.125.0
• previews.containers[].class_name (required): Durable Object class backed by the preview container. A class with no matching Durable Object is rejected; a class can back at most one container app, per release note.
• previews.containers[].image: Container image or Dockerfile path; docs example uses `./Dockerfile`. Release note recommends prebuilt `image` for JSON output.
• previews.containers[].max_instances: Maximum container instances; docs example uses `10`.
• previews.containers[].instance_type: Container instance type; docs example uses `basic`.
• --json: Return machine-readable output; defaults to false.
• Prerequisite: Container preview configuration is not inherited from top-level `containers`; declare it under `previews.containers`.
• Prerequisite: A Durable Object class and its SQLite migration are shown in the docs configuration example. A preview Durable Object binding is needed only when Worker code reads the namespace from `env`; it is unnecessary for access through `ctx.exports`.
• Prerequisite: The preview command's `SCRIPT` argument is needed only if the Wrangler config has no `main` key.
• Container configuration does not inherit; declare containers explicitly in the `previews` block.
• Each entry must set `class_name`.
• An entry cannot set its own `name`.
• A Durable Object class can be backed by at most one container application; validation rejects entries sharing a `class_name`.
• Entries whose `class_name` matches no Durable Object class are rejected before preview deployment.
• Wrangler skips container applications for Durable Object classes another Worker implements through `script_name`.
• A binding is not required when a Durable Object declared through `migrations` or `exports` is reached only over `ctx.exports`.
• Preview deletion tears down container applications server-side; `wrangler preview delete` does not remove them.
• Docker build output and the progress spinner write directly to stdout and bypass `--json` suppression; the spinner is skipped in non-interactive shells.
• `--json` suppresses Wrangler's own stdout output; warnings and errors still go to stderr.
• Docs conflict: Current Cloudflare preview docs say deleting a preview can leave its generated container app visible; they recommend checking `wrangler containers list` and deleting leftovers. This differs from the release note statement that preview deletion tears down container applications server-side. The docs page does not state the Wrangler version for that behavior.

FIRST-PARTY EVIDENCE

• https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.125.0
• https://github.com/cloudflare/cloudflare-docs/blob/production/src/content/docs/workers/previews/resources/index.mdx
• https://developers.cloudflare.com/workers/wrangler/commands/workers/

Check the installed version and the source before using it. Entry JSON

Report a problem with this card