Configuration

Previews do not inherit production settings. Define them in the previews block of your configuration file. For how bindings share or isolate data and state, refer to Resources and isolation.

Define your starting previews block on the branch your team branches from, such as main. Git carries the configuration file into each new branch.

Change the previews block on a branch when its Preview needs different settings. When you run npx wrangler preview, Wrangler uses the configuration file from your current branch as the source of truth. For setup instructions, refer to Get started.

Secrets cannot be stored in Wrangler configuration files. To preserve the branching model without applying the same secrets to every Preview manually, set shared secrets once in the Previews Base configuration. Each new Preview receives those secrets when it is created. Set a different value for an individual Preview when needed. Later changes to Base secrets apply only to new Previews, so active Previews remain unchanged.

The --name flag defaults to the current git branch if omitted.

Your Wrangler file has production settings at the top level and Preview settings in a previews block. The previews block is required, but it can be empty if your Preview does not need separate settings. Point Preview bindings at staging or test resources instead of production resources.

{
  // ...
  "vars": {
    "ENVIRONMENT": "production"
  },
  "r2_buckets": [
    {
      "binding": "UPLOADS",
      "bucket_name": "prod-uploads"
    }
  ],
  // ...
  "previews": {
    // ...
    "vars": {
      "ENVIRONMENT": "preview"
    },
    "r2_buckets": [
      {
        "binding": "UPLOADS",
        "bucket_name": "r2-staging"
      }
    ]
    // ...
  }
}

[vars]
ENVIRONMENT = "production"

[[r2_buckets]]
binding = "UPLOADS"
bucket_name = "prod-uploads"

[previews.vars]
ENVIRONMENT = "preview"

[[previews.r2_buckets]]
binding = "UPLOADS"
bucket_name = "r2-staging"

If npx wrangler preview creates a Preview URL but warns that bindings are missing, the URL is live but the runtime configuration is incomplete. Copy the missing bindings into the previews block, using Preview-safe values and test resources. For resource sharing behavior, refer to Resources and isolation.

Use this table to determine where each setting belongs.

If your Worker uses only top-level settings, include an empty previews block:

{
  // Set this to today's date
  "compatibility_date": "2026-10-02",
  "assets": {
    "directory": "./public"
  },
  "previews": {}
}

# Set this to today's date
compatibility_date = "2026-10-02"
previews = { }

[assets]
directory = "./public"

Do not add Queue consumers, Cron Triggers, or production routes to previews. These do not target Previews. For Preview hostnames, refer to Custom domains.

Service bindings from a Preview call the bound Worker's production deployment. For more limitations, refer to Limitations.

You can configure Previews Base settings in the dashboard, but you must copy the generated configuration into your Wrangler file. To avoid this extra step, configure your Preview settings in the Wrangler file directly.