Skip to content

Commit e60ca5e

Browse files
korinnekorinne
committed
[Workers] Add Previews overview page with intro, setup, deploy, URLs, observability, and limits
1 parent 3fe69d7 commit e60ca5e

1 file changed

Lines changed: 168 additions & 0 deletions

File tree

‎src/content/docs/workers/previews/index.mdx‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
pcx_content_type: overview
3+
title: Previews
4+
sidebar:
5+
order: 7
6+
badge:
7+
text: Beta
8+
description: Deploy isolated copies of your Worker to test changes before deploying to production.
9+
---
10+
11+
import {
12+
Render,
13+
WranglerConfig,
14+
Details,
15+
PackageManagers,
16+
Tabs,
17+
TabItem,
18+
InlineBadge,
19+
} from "~/components";
20+
21+
A Preview is an isolated copy of your Worker running on its own URL that you use to test changes before deploying to production. A Worker can have many Previews running at the same time, each isolated from each other. Each Preview runs with its own bindings, environment variables, and secrets, so your preview traffic never touches your production data.
22+
23+
Previews are created automatically when you push to any branch other than your tracked branch (usually `main`), or manually with `wrangler preview`.
24+
25+
## Quick start
26+
27+
1. Create a new project:
28+
29+
```bash
30+
npm create cloudflare@latest -- my-app --framework=astro --git --no-deploy -y
31+
```
32+
33+
2. Create a feature branch:
34+
35+
```bash
36+
git checkout -b new-feature
37+
```
38+
39+
3. Deploy a Preview:
40+
41+
```bash
42+
wrangler preview
43+
```
44+
45+
Wrangler builds your code locally and deploys it as a Preview. It prints a **Preview URL** and a **Deployment URL** to your terminal.
46+
47+
---
48+
49+
## Set up Previews
50+
51+
Previews use their own bindings, environment variables, and secrets -- separate from your production Worker settings. Before creating your first Preview, you need to configure what resources and environment variables Previews should use.
52+
53+
### From the dashboard
54+
55+
Go to your Worker > **Settings**, and you will see a banner for setting up your default Preview settings. This walks you through the bindings, environment variables, and observability settings you want every Preview to start with. This is the fastest way to get your whole team set up -- anyone who creates a Preview (manually or by pushing a branch) gets the same configuration without needing to specify it themselves.
56+
57+
### From code
58+
59+
Add a `previews` block to your Wrangler configuration file to specify bindings and environment variables that apply when you run `wrangler preview`. This is useful when you want Preview configuration checked into Git alongside your Worker code, or when you are working through a coding agent.
60+
61+
<WranglerConfig>
62+
63+
```toml
64+
# Top-level configuration is treated as production configuration
65+
name = "my-worker"
66+
main = "src/index.ts"
67+
compatibility_date = "$today"
68+
69+
[[kv_namespaces]]
70+
binding = "MY_KV"
71+
id = "prod-kv-id"
72+
73+
[previews]
74+
vars = { ENVIRONMENT = "preview" }
75+
76+
[[previews.kv_namespaces]]
77+
binding = "MY_KV"
78+
id = "preview-kv-id"
79+
```
80+
81+
</WranglerConfig>
82+
83+
When you configure settings in both the dashboard and the Wrangler configuration file, values from your Wrangler file take precedence for that deployment. Settings configured in the dashboard still apply to anything not overridden -- including Previews created by teammates or by automated builds triggered from Git pushes.
84+
85+
---
86+
87+
## Deploy a Preview
88+
89+
You can deploy a Preview automatically every time you push to a branch using Workers Builds, or manually from the command line with `wrangler preview`.
90+
91+
### Automate with Workers Builds
92+
93+
Connect a GitHub or GitLab repository, and Cloudflare deploys a Preview for you every time you push to a branch.
94+
95+
1. Go to **Workers & Pages** > your Worker > **Settings** > **Builds**.
96+
2. Connect your repository.
97+
3. Set your tracked branch (usually `main`).
98+
99+
When you push to `main`, Cloudflare builds and deploys your Worker to production using your top-level Wrangler configuration -- your production bindings, environment variables, and secrets. When you push to any other branch, Cloudflare deploys a Preview using your Preview settings instead.
100+
101+
The first push to a branch creates a new Preview. Each subsequent push creates a new deployment within that Preview -- an immutable snapshot of your code at that point. This means you can always go back and inspect or compare any previous deployment, even after pushing new changes.
102+
103+
A bot comments on your pull request with:
104+
105+
- A link to the **Preview URL** (which always serves the latest deployment)
106+
- A **Deployment URL** (which points to that exact snapshot)
107+
- A link to the build logs
108+
109+
### Deploy manually with Wrangler
110+
111+
Run `wrangler preview` from your project directory to build your code locally and deploy it as a Preview:
112+
113+
```bash
114+
wrangler preview
115+
```
116+
117+
By default, Wrangler names the Preview after your current Git branch. You can also provide a name explicitly:
118+
119+
```bash
120+
wrangler preview --name my-feature
121+
```
122+
123+
If a Preview with that name does not exist yet, Wrangler creates it. If it already exists, Wrangler creates a new deployment within it. Each time you run `wrangler preview`, Wrangler prints the Preview URL and Deployment URL to your terminal.
124+
125+
Use this for ad-hoc testing, external CI/CD pipelines, or when you are not using a Git-based workflow.
126+
127+
---
128+
129+
## Preview URLs and Deployment URLs
130+
131+
When you deploy a Preview, Cloudflare generates two URLs:
132+
133+
- **Preview URL** -- always serves the latest deployment. When you push new code, the Preview URL points to the new deployment automatically. Share this with teammates when you want them to always see your latest changes.
134+
135+
```txt
136+
https://my-feature-my-worker.my-account.workers.dev
137+
```
138+
139+
- **Deployment URL** -- points to one specific deployment and never changes, even after you push newer code. Use this to pin to an exact version -- for example, to compare two deployments side by side or to link to the exact build that a reviewer approved.
140+
141+
```txt
142+
https://f498jo-my-worker.my-account.workers.dev
143+
```
144+
145+
Workers Builds posts both URLs as a comment on your pull request. `wrangler preview` prints both to your terminal.
146+
147+
---
148+
149+
## Observability and logging
150+
151+
Each Preview runs its own observability and logging settings, independent of your production Worker. This means you can:
152+
153+
- Set full sampling (`head_sampling_rate: 1`) on a Preview to capture every request during testing, without increasing log volume on your production Worker.
154+
- Enable [Logpush](/workers/observability/logpush/) to send a Preview's logs to your own storage for debugging.
155+
- Attach [Tail Workers](/workers/observability/logs/tail-workers/) to a Preview to pipe its logs into a custom analysis pipeline.
156+
157+
Configure these in the dashboard under **Workers & Pages** > your Worker > **Settings** > **Preview Defaults**, and Cloudflare applies them to every Preview created for that Worker.
158+
159+
---
160+
161+
## Limits and lifecycle
162+
163+
- Previews do not count against the account-level Worker limit (100 free / 500 paid). They have a separate limit: **1,000** for free plans, **10,000** for paid plans.
164+
- If you hit the limit, creating a new Preview automatically deletes the least-recently-deployed existing Preview to make room.
165+
- Previews are automatically deleted after a TTL since their last deployment.
166+
- Previews cannot be addressed by user-managed triggers (routes, cron triggers, queues). They are reachable only through their auto-generated URLs and custom-domain wildcard URLs.
167+
- [Service bindings](/workers/runtime-apis/bindings/service-bindings/) on a Preview always target the production instance of the bound Worker. You cannot point a service binding at another Preview.
168+
- Previews cannot be gradually deployed. All other runtime features -- [Durable Objects](/durable-objects/), observability, [placement](/workers/configuration/smart-placement/), [Tail Workers](/workers/observability/logs/tail-workers/) -- are supported.

0 commit comments

Comments
 (0)