Skip to content

Commit aa48344

Browse files
markjmillermarkjmiller
committed
docs: workers environments
1 parent cbe2de1 commit aa48344

File tree

1 file changed

+175
-0
lines changed

1 file changed

+175
-0
lines changed

‎src/content/docs/workers/development-testing/workers-environments.mdx‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
title: Workers Environments
3+
pcx_content_type: concept
4+
sidebar:
5+
order: 11
6+
---
7+
8+
Workers Environments is a pattern that combines [Wrangler Environments](/workers/wrangler/environments/) and [Workers Build](/workers/ci-cd/builds/) to create a powerful deployment workflow for your git-connected Workers projects. By following this guide, you'll set up separate production and preview environments with isolated resources and a convenient preview URL that's automatically added to your PRs. This enables you to safely test changes before deploying to production.
9+
10+
## Benefits
11+
12+
When properly configured, Workers Environments provides:
13+
14+
- Automatic PR preview deployments with a comment containing a preview URL
15+
- Isolated resources between environments (variables, bindings, databases, etc.)
16+
- A unified dashboard view that groups your environments under a single service
17+
- Clean versioning and deployment history for your production environment
18+
19+
## Key concepts
20+
21+
Before getting started, let's clarify some terminology:
22+
23+
- **Production Worker** - Your main Worker that serves production traffic
24+
- **Preview Worker** - A separate Worker instance for testing changes before they reach production
25+
- **Feature branch** - Any branch that isn't your production branch (typically branches other than `main` or `production`)
26+
27+
## Automatic setup
28+
29+
[Deploy to Cloudflare](/workers/platform/deploy-buttons/) will guide you through a setup flow to connect to GitHub or GitLab and will set up a Production and Preview environment with the right build config by default. Check out [Workers Templates](https://github.com/cloudflare/templates) to get started now!
30+
31+
## Setting up Workers Environments manually
32+
33+
### 1. Configure your Workers project with environments
34+
35+
Create or modify your `wrangler.json` file to include environment-specific configurations. Here's an example with different variables and D1 db instances for production and preview:
36+
37+
```json
38+
{
39+
"compatibility_date": "2025-04-01",
40+
"main": "src/index.ts",
41+
"name": "cool-service",
42+
"env": {
43+
"production": {
44+
"route": "example.com",
45+
"vars": {
46+
"ENVIRONMENT": "production"
47+
},
48+
"d1_databases": [
49+
{
50+
"binding": "DB",
51+
"database_id": "a90fb4ab-a580-47ef-81e0-31f643ae14cb",
52+
"database_name": "cool-service-db-production"
53+
}
54+
]
55+
},
56+
"preview": {
57+
"vars": {
58+
"ENVIRONMENT": "preview"
59+
},
60+
"d1_databases": [
61+
{
62+
"binding": "DB",
63+
"database_id": "f8121f01-cbe8-48c3-c799-9a4cf94bde93",
64+
"database_name": "cool-service-db-preview"
65+
}
66+
]
67+
}
68+
}
69+
}
70+
```
71+
72+
:::note
73+
74+
We don't need to assign a route to the preview environment because the [branch preview url](/workers/configuration/previews/) will effectively be the same thing. A [workers.dev subdomain](/workers/configuration/routing/workers-dev/) is also available out-of-the-box. However, you could create another custom, stable route if you'd like.
75+
:::
76+
77+
### 2. Deploy both environments
78+
79+
Deploy both environments to create the Workers:
80+
81+
```sh
82+
npx wrangler deploy --env production
83+
npx wrangler deploy --env preview
84+
```
85+
86+
When Wrangler deploys with the `--env` flag, it creates Workers with names like `cool-service-production` and `cool-service-preview`. These will be grouped as a single service in the dashboard.
87+
88+
### 3. Configure Workers Build for your Production Worker
89+
90+
Now, set up CI/CD for your production environment:
91+
92+
1. Navigate to your Worker in the Cloudflare dashboard
93+
2. Go to the **Build** tab
94+
3. Click **Git repository > Connect**
95+
4. Configure your build settings:
96+
97+
- **Branch**: `main` (or your production branch)
98+
- **Build command**: `npm run build` (or your build command)
99+
- **Deploy command**: `npx wrangler deploy --env production`
100+
- **Enable non-production branch builds**: Unchecked
101+
- **Build variables**: Add any variables needed for your production environment
102+
103+
TODO: Add screenshot of Production Worker build configuration
104+
105+
### 4. Configure Workers Build for your Preview Worker
106+
107+
Set up CI/CD for your preview environment:
108+
109+
1. Navigate to your Worker in the Cloudflare dashboard
110+
2. Go to the **Build** tab
111+
3. Click **Git repository > Connect**
112+
4. Configure your build settings:
113+
114+
- **Branch**: `main` (or your production branch)
115+
- **Build command**: `npm run build` (or your build command)
116+
- **Deploy command**: `npx wrangler deploy --env preview`
117+
- **Enable non-production branch builds**: Checked
118+
- **Non-production branch deploy command**: `npx wrangler versions upload --env preview --preview-alias $WORKERS_CI_BRANCH`
119+
- **Build variables**: Add any variables needed for your preview environment
120+
121+
TODO: Add screenshot of Preview Worker build configuration
122+
123+
### 5. Test your setup
124+
125+
1. Create a feature branch from your main branch
126+
2. Make changes and push them
127+
3. Create a pull request to your main branch
128+
129+
You should see a comment on the PR with the title "Deploying with Cloudflare Workers" and a preview URL. This URL routes to your Preview Worker, which uses your preview variables, secrets, and resources.
130+
131+
TODO: Add screenshot of PR comment with preview URL
132+
133+
### 6. Deploy to production
134+
135+
When you merge the PR, the Production Worker will build and deploy automatically. Since each environment is a separate Worker, your production deployment history remains clean and focused only on production changes.
136+
137+
## Viewing your environments in the dashboard
138+
139+
When you deploy Workers using Wrangler Environments, they appear as a single service in the Workers dashboard instead of separate `<worker-name>-<environment-name>` workers. Under the hood, this is driven by tags on the Workers: `service=<worker_name>` and `environment=<environment_name>` (TODO haven't settled on this yet).
140+
141+
Inside this view, you'll find an environments dropdown that allows you to switch between different environments (which are separate Workers).
142+
143+
TODO: Add screenshot of the Workers dashboard showing the environments dropdown
144+
145+
## Debugging preview environments
146+
147+
Since each environment is a standalone Worker, you can debug them individually, such as with Wrangler:
148+
149+
```sh
150+
wrangler tail cool-service --env preview
151+
```
152+
153+
It still has its own [Workers Observability](/workers/observability) and metrics in the dashboard, too.
154+
155+
## Migrating from Workers
156+
157+
TODO
158+
159+
## Migrating from Pages
160+
161+
If you're currently using [Pages](/pages/) and want to migrate to Workers Environments: TODO
162+
163+
## Additional setups
164+
165+
### Using Workers Environments without Wrangler
166+
167+
If you're not using Wrangler, you can still implement Workers Environments by tagging your Workers in the API.
168+
169+
TODO: Add details about API tagging for Workers Environments
170+
171+
### Using Workers Environments without Workers Build
172+
173+
If you prefer using other CI/CD tools like GitHub Actions instead of Workers Build, you can still implement Workers Environments.
174+
175+
TODO

0 commit comments

Comments
 (0)