Skip to content

Commit e3ccd4f

Browse files
korinnekorinne
committed
[Workers] Polish Previews docs: remove Beta badges, replace -- with em dashes, add doc links, use PackageManagers components
1 parent 9bd5306 commit e3ccd4f

2 files changed

Lines changed: 48 additions & 57 deletions

File tree

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

Lines changed: 28 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@ pcx_content_type: reference
33
title: Previews API
44
sidebar:
55
order: 2
6-
badge:
7-
text: Beta
6+
87
description: Understand the Previews data model and use the API to manage Previews and Deployments programmatically.
98
---
109

@@ -26,15 +25,15 @@ https://api.cloudflare.com/client/v4/accounts/{account_id}/workers
2625

2726
#### Preview
2827

29-
A **Preview** is a fully functional Worker that Cloudflare creates as a child of your production Worker. It runs on the same infrastructure, supports the same bindings, and handles traffic the same way -- but it operates in complete isolation. Requests to a Preview never touch your production Worker's data or configuration.
28+
A **Preview** is a fully functional Worker that Cloudflare creates as a child of your production Worker. It runs on the same infrastructure, supports the same [bindings](/workers/runtime-apis/bindings/), and handles traffic the same way — but it operates in complete isolation. Requests to a Preview never touch your production Worker's data or configuration.
3029

31-
Every Preview belongs to exactly one parent Worker. You can create as many Previews as you need -- one per feature branch, one per teammate, or one for every pull request.
30+
Every Preview belongs to exactly one parent Worker. You can create as many Previews as you need — one per feature branch, one per teammate, or one for every pull request.
3231

3332
#### Preview Deployment
3433

3534
A **Preview Deployment** is an immutable version of your Worker code, bindings, and configuration. It belongs to a single Preview and cannot be modified after creation.
3635

37-
A Preview can have many Deployments, but it only serves traffic from one at a time. Creating a new Deployment automatically makes it the active one -- 100% of the Preview's traffic switches to it immediately. There is no gradual rollout.
36+
A Preview can have many Deployments, but it only serves traffic from one at a time. Creating a new Deployment automatically makes it the active one — 100% of the Preview's traffic switches to it immediately. There is no gradual rollout.
3837

3938
Together, Previews and their Deployments form a hierarchy:
4039

@@ -72,9 +71,9 @@ The Previews API splits configuration into two layers: the **Preview layer** and
7271

7372
The **Preview layer** holds settings that apply across all of a Preview's Deployments: observability, log routing (`logpush`, `tail_consumers`), and organizational metadata (`tags`). These persist for the lifetime of the Preview regardless of how many Deployments you create.
7473

75-
Each **Deployment** holds settings that are locked in at creation time and never change -- your Worker code (`main_module`, `modules`), `bindings`, `compatibility_date`, `compatibility_flags`, `limits`, `placement`, `assets`, `migrations`, and `annotations`.
74+
Each **Deployment** holds settings that are locked in at creation time and never change — your Worker code (`main_module`, `modules`), `bindings`, `compatibility_date`, `compatibility_flags`, `limits`, `placement`, `assets`, `migrations`, and `annotations`.
7675

77-
This split matters because everything downstream -- Preview Defaults, the merge behavior, and which endpoints accept which fields -- follows from it.
76+
This split matters because everything downstream — Preview Defaults, the merge behavior, and which endpoints accept which fields — follows from it.
7877

7978
---
8079

@@ -171,31 +170,31 @@ The Deployment object represents the Deployment layer. Here is its full shape:
171170
}
172171
```
173172

174-
| Field | Description |
175-
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
176-
| `id` | UUID assigned at creation. |
177-
| `number` | Sequential deployment number starting from 1. |
178-
| `startup_time_ms` | Time in milliseconds the Worker took to start up. |
179-
| `main_module` | Name of the entry-point module (the one that exports a `fetch` handler). |
180-
| `modules` | Array of code and sourcemap content. Each entry has `name`, `content_type`, and `content_base64`. Only included in responses when you pass `?include=modules`. |
181-
| `bindings` | KV namespaces, D1 databases, secrets, plain-text vars, service bindings, and so on. |
182-
| `compatibility_date` | The [compatibility date](/workers/configuration/compatibility-dates/) for runtime behavior. |
183-
| `compatibility_flags` | Array of [compatibility flags](/workers/configuration/compatibility-dates/). |
184-
| `limits` | Runtime resource limits, for example `{ "cpu_ms": 50 }`. |
185-
| `placement` | [Smart placement](/workers/configuration/smart-placement/) configuration. |
186-
| `usage_model` | Deprecated. One of `standard`, `bundled`, `unbound`. |
187-
| `assets` | Static asset configuration (`html_handling`, `not_found_handling`, `run_worker_first`). |
188-
| `migrations` | [Durable Object migrations](/durable-objects/reference/durable-objects-migrations/). Applied when the Deployment is created. |
189-
| `annotations` | Metadata: `workers/message` (human-readable, max 100 chars), `workers/tag` (for example, a semver string, max 25 chars), `workers/triggered_by` (read-only, set by the system). |
190-
| `urls` | Read-only. The routable URLs that always point to this exact Deployment. |
191-
| `source` | Read-only. The client that created the Deployment (for example, `wrangler`, `api`). |
192-
| `created_on` | Read-only. When the Deployment was created. |
173+
| Field | Description |
174+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
175+
| `id` | UUID assigned at creation. |
176+
| `number` | Sequential deployment number starting from 1. |
177+
| `startup_time_ms` | Time in milliseconds the Worker took to start up. |
178+
| `main_module` | Name of the entry-point module (the one that exports a `fetch` handler). |
179+
| `modules` | Array of code and sourcemap content. Each entry has `name`, `content_type`, and `content_base64`. Only included in responses when you pass `?include=modules`. |
180+
| `bindings` | [KV namespaces](/kv/), [D1 databases](/d1/), [secrets](/workers/configuration/secrets/), plain-text vars, [service bindings](/workers/runtime-apis/bindings/service-bindings/), and so on. |
181+
| `compatibility_date` | The [compatibility date](/workers/configuration/compatibility-dates/) for runtime behavior. |
182+
| `compatibility_flags` | Array of [compatibility flags](/workers/configuration/compatibility-dates/). |
183+
| `limits` | Runtime resource limits, for example `{ "cpu_ms": 50 }`. |
184+
| `placement` | [Smart placement](/workers/configuration/smart-placement/) configuration. |
185+
| `usage_model` | Deprecated. One of `standard`, `bundled`, `unbound`. |
186+
| `assets` | Static asset configuration (`html_handling`, `not_found_handling`, `run_worker_first`). |
187+
| `migrations` | [Durable Object migrations](/durable-objects/reference/durable-objects-migrations/). Applied when the Deployment is created. |
188+
| `annotations` | Metadata: `workers/message` (human-readable, max 100 chars), `workers/tag` (for example, a semver string, max 25 chars), `workers/triggered_by` (read-only, set by the system). |
189+
| `urls` | Read-only. The routable URLs that always point to this exact Deployment. |
190+
| `source` | Read-only. The client that created the Deployment (for example, `wrangler`, `api`). |
191+
| `created_on` | Read-only. When the Deployment was created. |
193192

194193
---
195194

196195
## Preview Defaults
197196

198-
Your production Worker can store a property called **`preview_defaults`**. It is a template of starting values that Cloudflare applies whenever you create a new Preview or Deployment. It is not a standalone API resource -- you read and write it through the existing Worker endpoints (`PUT` or `PATCH` on `/workers/workers/{worker_id}`). You can also configure these from the dashboard or your Wrangler configuration file -- refer to [Set up Previews](/workers/previews/#set-up-previews) for a walkthrough.
197+
Your production Worker can store a property called **`preview_defaults`**. It is a template of starting values that Cloudflare applies whenever you create a new Preview or Deployment. It is not a standalone API resource — you read and write it through the existing Worker endpoints (`PUT` or `PATCH` on `/workers/workers/{worker_id}`). You can also configure these from the dashboard or your Wrangler configuration file — refer to [Set up Previews](/workers/previews/#set-up-previews) for a walkthrough.
199198

200199
`preview_defaults` carries values for both layers:
201200

@@ -248,8 +247,6 @@ Your request body wins for any field it provides. Fields absent from your reques
248247

249248
To skip the merge entirely and use only your request body, pass `?ignore_defaults=true`. This is supported on **Create Preview**, **Update Preview (PUT)**, and **Create Deployment**.
250249

251-
### Worked example
252-
253250
<Details header="Worked example: creating a Preview and Deployment with defaults">
254251

255252
Parent Worker has these `preview_defaults`:
@@ -366,7 +363,7 @@ PUT /workers/workers/{worker_id}
366363
PATCH /workers/workers/{worker_id}
367364
```
368365

369-
Example (`PATCH` -- only touches `preview_defaults`, leaves everything else unchanged):
366+
Example (`PATCH` — only touches `preview_defaults`, leaves everything else unchanged):
370367

371368
```bash
372369
curl -X PATCH \
@@ -525,7 +522,7 @@ DELETE /{deployment_id}
525522

526523
### 1. Set Preview Defaults on your Worker
527524

528-
This is a one-time setup step. You are patching the parent Worker, not creating a new resource. You can also do this from the dashboard or Wrangler -- refer to [Set up Previews](/workers/previews/#set-up-previews).
525+
This is a one-time setup step. You are patching the parent Worker, not creating a new resource. You can also do this from the dashboard or Wrangler — refer to [Set up Previews](/workers/previews/#set-up-previews).
529526

530527
```bash
531528
curl -X PATCH \

0 commit comments

Comments
 (0)