Workers - Test every pull request in an isolated environment with Worker Previews

<p>You can now test every change you make in an isolated, production-like environment with <a href="https://blog.cloudflare.com/worker-previews/" target="_blank" rel="noopener">Worker Previews<span class="external-link"> ↗︎</span></a>. <a href="https://developers.cloudflare.com/workers/previews/">Each Preview</a> runs under the same Worker with its own code, configuration, URL, and observability, isolated from production and every other Preview.</p> <div tabindex="-1" class="heading-wrapper level-h4"><h4 id="configure-each-preview">Configure each Preview</h4><a class="anchor-link" href="#configure-each-preview"><span aria-hidden="true" class="anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span></a></div> <p>Define the variables, bindings, and settings that new Previews start with in the <a href="https://developers.cloudflare.com/workers/previews/configuration/"><code>previews</code> block of your Wrangler configuration file</a>. Set secrets with Wrangler commands. You can override one Preview without changing production or other Previews.</p> <p>For <a href="https://developers.cloudflare.com/workers/previews/resources/#durable-objects">Durable Objects</a> and <a href="https://developers.cloudflare.com/workers/previews/resources/#containers">Containers</a>, Cloudflare automatically provisions separate namespaces, storage, apps, and instances for every Preview. State changes, sessions, memory, migrations, and concurrent tests remain scoped to that Preview. To isolate KV, D1, R2, or another account-level resource, <a href="https://developers.cloudflare.com/workers/previews/resources/">bind the Preview to a separate resource</a>.</p> <img src="https://developers.cloudflare.com/cdn-cgi/image/onerror=redirect,width=1999,height=1370,format=webp/_astro/preview-resource-isolation.CyeUXRJS.png" alt="Diagram comparing production with three Previews, each with its own URL, code, configuration, and Durable Object state" loading="lazy" decoding="async" width="1999" height="1370"> <div tabindex="-1" class="heading-wrapper level-h4"><h4 id="deploy-and-share-every-change">Deploy and share every change</h4><a class="anchor-link" href="#deploy-and-share-every-change"><span aria-hidden="true" class="anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span></a></div> <p>Use Wrangler 4.135.0 or later to <a href="https://developers.cloudflare.com/workers/previews/get-started/">deploy a Preview</a>:</p> <figure class="nb-code-figure" data-nb-lang="sh"><pre class="astro-code astro-code-themes github-light github-dark nb-shiki-c6xiwz" tabindex="0" data-language="sh" data-nb-lang="sh"><code><span class="line"><span class="nb-shiki-1t8gfj">npx</span><span class="nb-shiki-mdbnqw"> wrangler</span><span class="nb-shiki-mdbnqw"> preview</span></span></code></pre></figure> <p>Or <a href="https://developers.cloudflare.com/workers/ci-cd/builds/build-branches/#configure-preview-builds">connect your repository to Workers Builds</a> to create Previews automatically and post their URLs to pull requests.</p> <p>Each Preview gets a <a href="https://developers.cloudflare.com/workers/previews/#urls">stable URL</a> that updates with every push, so reviewers always see the latest changes. Each deployment also gets an immutable URL, so you can compare or return to an exact version.</p> <p>After you create a Preview, use the environment breadcrumb next to your Worker's name to switch between Production and every Preview:</p> <img src="https://developers.cloudflare.com/cdn-cgi/image/onerror=redirect,width=2386,height=1304,format=webp/_astro/previews-dash-overview.BL1UHZHT.png" alt="Worker dashboard showing the Preview dropdown and an overview of bindings, metrics, and deployments" loading="lazy" decoding="async" width="2386" height="1304"> <div tabindex="-1" class="heading-wrapper level-h4"><h4 id="inspect-and-revise-before-production">Inspect and revise before production</h4><a class="anchor-link" href="#inspect-and-revise-before-production"><span aria-hidden="true" class="anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span></a></div> <p>Each Preview has its own <a href="https://developers.cloudflare.com/workers/previews/test-and-debug/">logs, errors, metrics, and traces</a>. Send traffic to its URL, inspect what happened, push a fix, and verify the next deployment before production.</p> <img src="https://developers.cloudflare.com/cdn-cgi/image/onerror=redirect,width=1418,height=1236,format=webp/_astro/preview-observability.COYT0y5H.png" alt="Preview Observability tab showing success and error events for a pull request" loading="lazy" decoding="async" width="1418" height="1236"> <div tabindex="-1" class="heading-wrapper level-h4"><h4 id="use-production-like-hostnames">Use production-like hostnames</h4><a class="anchor-link" href="#use-production-like-hostnames"><span aria-hidden="true" class="anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span></a></div> <p>Serve Preview URLs on <code>workers.dev</code>, a <a href="https://developers.cloudflare.com/workers/previews/custom-domains/">custom domain</a>, or both. Custom domains let authentication providers, cookies, cross-origin resource sharing (CORS), and OAuth redirects work as they will in production. You can also protect Preview URLs with Cloudflare Access.</p> <p>Configure a domain for Preview traffic from the Worker's <strong>Domains</strong> tab:</p> <img src="https://developers.cloudflare.com/cdn-cgi/image/onerror=redirect,width=2876,height=1454,format=webp/_astro/customdomainonly.8AG_6tc-.png" alt="Domains tab showing a custom domain configured for Preview traffic" loading="lazy" decoding="async" width="2876" height="1454"> <p>For setup instructions and current limitations, refer to the <a href="https://developers.cloudflare.com/workers/previews/">Worker Previews documentation</a>.</p>