Custom domains

Preview URLs can use a custom domain, workers.dev, or both. Enable at least one host to get a Preview URL.

Host	Preview URL	Unique deployment URL
Custom domain	`<preview-name>.app.example.com`	`<deployment-id>-<preview-name>.app.example.com`
`workers.dev`	`<preview-name>-<worker-name>.<subdomain>.workers.dev`	`<deployment-id>-<worker-name>.<subdomain>.workers.dev`

Before you start

Configure Previews in the same system that manages your custom domain:

Managed with	Configuration
Wrangler	Use the Wrangler tab, then run `npx wrangler deploy`.
Dashboard	Use the Dashboard tab.
Terraform	Update and apply your Terraform configuration.

Enable custom domain Preview URLs

Wrangler

Dashboard

The following example configures app.example.com for Preview traffic only. Add previews_enabled and set enabled to false, then run npx wrangler deploy to apply the configuration.

wrangler.jsonc

wrangler.toml

{
  "routes": [
    {
      "pattern": "app.example.com",
      "custom_domain": true,
      "previews_enabled": true,
      "enabled": false
    }
  ]
}

[[routes]]
pattern = "app.example.com"
custom_domain = true
previews_enabled = true
enabled = false

Choose which traffic the custom domain serves:

Traffic	`previews_enabled`	`enabled`
Preview only	`true`	`false`
Production and Preview	`true`	Omit or set `true`

In the Cloudflare dashboard, go to Workers & Pages and select your Worker.

dash.cloudflare.com
On the Domains tab, under Custom Domains and Routes, select + Add Domain.
Enter your domain. For Enable for, select Preview or Production and Preview. Then select Add domain.
Confirm that the domain appears under Custom Domains and Routes.

Enable `workers.dev` Preview URLs

Production and Preview workers.dev URLs are configured separately.

Wrangler

Dashboard

Set preview_urls in your Wrangler configuration file, then run npx wrangler deploy.

wrangler.jsonc

wrangler.toml

{
  "preview_urls": true
}

preview_urls = true

If preview_urls is omitted, Wrangler does not change an existing Preview URL setting. If no setting exists, its initial value depends on workers_dev. Set preview_urls explicitly to change the Preview URL setting.

In the Cloudflare dashboard, go to Workers & Pages and select your Worker.

dash.cloudflare.com
On the Domains tab, under Worker URL, turn on Preview.

Protect Preview content

To restrict access to custom domain and workers.dev Preview URLs, use Cloudflare Access. This prevents unauthenticated users and crawlers from viewing your Preview.

To keep a Preview public while discouraging search engine indexing, add an X-Robots-Tag: noindex response header. Cloudflare adds this header automatically to workers.dev Preview URLs, but not to custom domain Preview URLs.

For static assets, add the header through a _headers file. For Worker-generated responses, add it directly in your Worker code.