Skip to content

Custom domains

Last updated View as MarkdownAgent setup

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

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.

{
  "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

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

    Go to Workers & Pages ↗

  2. On the Domains tab, under Custom Domains and Routes, select + Add Domain.

  3. Enter your domain. For Enable for, select Preview or Production and Preview. Then select Add domain.

    Add Domain modal with Enable for set to Preview

  4. Confirm that the domain appears under Custom Domains and Routes.

    Domains tab showing a custom domain enabled for Preview traffic

DNS and certificate behavior

Cloudflare creates a wildcard DNS record and SSL certificate for the custom domain, such as *.app.example.com. Certificate issuance can take time after you create the first Preview.

Use a dedicated hostname such as previews.example.com if your production domain already has subdomains. This avoids wildcard conflicts.

Preview URLs add another subdomain to your hostname. For example, app.preview.example.com creates <preview-name>.app.preview.example.com. For deeper hostnames, you may need Advanced Certificate Manager with Total TLS or another certificate that covers the Preview hostname.

Enable workers.dev Preview URLs

Production and Preview workers.dev URLs are configured separately.

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

{
  "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.

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

    Go to Workers & Pages ↗

  2. On the Domains tab, under Worker URL, turn on Preview.

    Domains tab showing workers.dev Preview URLs enabled with no custom domains configured

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.

Was this helpful?