Skip to content

Commit dee994f

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

File tree

1 file changed

+165
-0
lines changed

1 file changed

+165
-0
lines changed

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

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
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+
"vars": {
45+
"ENVIRONMENT": "production"
46+
},
47+
"d1_databases": [
48+
{
49+
"binding": "DB",
50+
"database_id": "a90fb4ab-a580-47ef-81e0-31f643ae14cb",
51+
"database_name": "cool-service-db-production"
52+
}
53+
]
54+
},
55+
"preview": {
56+
"vars": {
57+
"ENVIRONMENT": "preview"
58+
},
59+
"d1_databases": [
60+
{
61+
"binding": "DB",
62+
"database_id": "f8121f01-cbe8-48c3-c799-9a4cf94bde93",
63+
"database_name": "cool-service-db-preview"
64+
}
65+
]
66+
}
67+
}
68+
}
69+
```
70+
71+
### 2. Deploy both environments
72+
73+
Deploy both environments to create the Workers:
74+
75+
```sh
76+
npx wrangler deploy --env production
77+
npx wrangler deploy --env preview
78+
```
79+
80+
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.
81+
82+
### 3. Configure Workers Build for your Production Worker
83+
84+
Now, set up CI/CD for your production environment:
85+
86+
1. Navigate to your Worker in the Cloudflare dashboard
87+
2. Go to the **Build** tab
88+
3. Click **Git repository > Connect**
89+
4. Configure your build settings:
90+
91+
- **Branch**: `main` (or your production branch)
92+
- **Build command**: `npm run build` (or your build command)
93+
- **Deploy command**: `npx wrangler deploy --env production`
94+
- **Enable non-production branch builds**: Unchecked
95+
- **Build variables**: Add any variables needed for your production environment
96+
97+
TODO: Add screenshot of Production Worker build configuration
98+
99+
### 4. Configure Workers Build for your Preview Worker
100+
101+
Set up CI/CD for your preview environment:
102+
103+
1. Navigate to your Worker in the Cloudflare dashboard
104+
2. Go to the **Build** tab
105+
3. Click **Git repository > Connect**
106+
4. Configure your build settings:
107+
108+
- **Branch**: `main` (or your production branch)
109+
- **Build command**: `npm run build` (or your build command)
110+
- **Deploy command**: `npx wrangler deploy --env preview`
111+
- **Enable non-production branch builds**: Checked
112+
- **Non-production branch deploy command**: `npx wrangler versions upload --env preview --preview-alias $WORKERS_CI_BRANCH`
113+
- **Build variables**: Add any variables needed for your preview environment
114+
115+
TODO: Add screenshot of Preview Worker build configuration
116+
117+
### 5. Test your setup
118+
119+
1. Create a feature branch from your main branch
120+
2. Make changes and push them
121+
3. Create a pull request to your main branch
122+
123+
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.
124+
125+
TODO: Add screenshot of PR comment with preview URL
126+
127+
### 6. Deploy to production
128+
129+
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.
130+
131+
## Viewing your environments in the dashboard
132+
133+
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).
134+
135+
Inside this view, you'll find an environments dropdown that allows you to switch between different environments (which are separate Workers).
136+
137+
TODO: Add screenshot of the Workers dashboard showing the environments dropdown
138+
139+
## Debugging preview environments
140+
141+
Since each environment is a standalone Worker, you can debug them individually, such as with Wrangler:
142+
143+
```sh
144+
wrangler tail cool-service --env preview
145+
```
146+
147+
It still has its own [Workers Observability](/workers/observability) and metrics in the dashboard, too.
148+
149+
## Additional setups
150+
151+
### Using Workers Environments without Wrangler
152+
153+
If you're not using Wrangler, you can still implement Workers Environments by tagging your Workers in the API.
154+
155+
TODO: Add details about API tagging for Workers Environments
156+
157+
### Using Workers Environments without Workers Build
158+
159+
If you prefer using other CI/CD tools like GitHub Actions instead of Workers Build, you can still implement Workers Environments.
160+
161+
TODO
162+
163+
### Migrating from Pages
164+
165+
If you're currently using [Pages](/pages/) and want to migrate to Workers Environments: TODO

0 commit comments

Comments
 (0)