# Add a Staging Environment to a Cloudflare Worker

Yes. An agent adds staging and production environments to your Worker's wrangler config, each with its own D1 database, vars and deploy scripts, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-staging-environment/cloudflare-workers/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the Worker into its own cloud sandbox and reads its configuration before it adds an environment. In a Worker like `d1-template` in cloudflare/templates, `wrangler.json` names the Worker `d1-template`, points `main` at `src/index.ts`, sets `compatibility_date` to `2025-10-08`, turns on `observability` and `upload_source_maps`, and binds one D1 database as `DB` with `database_name` `d1-template-database` and a fixed `database_id`. There is no `env` block, no `vars` and no `routes`, so every `wrangler deploy` goes to the same Worker and the same database. `package.json` pins `wrangler` 4.136.1 and `typescript` 5.9.3, and its scripts tell the story: `predeploy` runs `wrangler d1 migrations apply DB --remote`, `deploy` runs `wrangler deploy`, `dev` seeds the local database first, and `check` runs `tsc && wrangler deploy --dry-run`.

Wrangler environments are the mechanism, and their one rule shapes the change: bindings such as `d1_databases` and `vars` are not inherited, so each environment must declare its own. The agent adds `env.staging` and `env.production` to `wrangler.json`, each with a `d1_databases` entry bound as `DB` but naming a different database (`d1-template-database-staging` and the existing one), and a `vars` block with an `ENVIRONMENT` value so code and logs can tell them apart. The top-level config stays as the local default that `wrangler dev` uses. Because the staging database does not exist yet, the agent writes its `database_id` as a clearly marked placeholder and records the `wrangler d1 create` command in the README, next to the existing setup steps that already tell a reader to paste a database id into the config. The same repository shows the pattern: `internal-sites-template/wrangler.jsonc` carries an `env.local` block that redeclares its D1 and `vars`.

Scripts and types change with it. `package.json` gains `deploy:staging` and `deploy:production` that run `wrangler deploy --env staging` and `--env production`, `migrate:staging` and `migrate:production` that apply D1 migrations with the matching `--env`, and `check` grows to run `wrangler deploy --dry-run` for both environments so a missing binding fails before anyone deploys. `src/index.ts` reads `env.ENVIRONMENT` and passes it to `renderHtml`, so the page says which environment served it, and `worker-configuration.d.ts` is regenerated with `wrangler types` so `Env` carries the new variable and `tsc` checks its use. The generated file's header shows the `workerd` version and date it came from, so the agent commits the regenerated version rather than editing it by hand.

Checking happens without a Cloudflare account. `wrangler deploy --dry-run --env staging` bundles the Worker and validates the config for that environment, and the agent runs it for both environments and for the default, followed by `tsc`. In the templates monorepo the pull request workflow also runs `pnpm -w check`, which includes the `templates lint` rules, Prettier and the per-template `check` scripts, and a Playwright smoke test in `playwright-tests/d1-template.spec.ts` that expects the comments query on the page; the agent keeps that heading intact so the smoke test still passes. If the Project holds a `CLOUDFLARE_API_TOKEN` as a secret, the prompt can ask the agent to create the staging database and apply its migrations too; otherwise it stops at the dry runs and says so.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add staging and production environments to this Cloudflare Worker. Read wrangler.json (or wrangler.jsonc/toml), package.json, src/*, migrations/*, worker-configuration.d.ts and the README first. Add env.staging and env.production to the Wrangler config, each with its own d1_databases binding named DB (staging gets a new database name and a placeholder database_id; production keeps the existing database) and a vars.ENVIRONMENT value, leaving the top-level config as the local default. Add deploy:staging, deploy:production, migrate:staging and migrate:production scripts, and make the check script run wrangler deploy --dry-run for the default, staging and production. Read env.ENVIRONMENT in the Worker and show it in the rendered page without changing the existing heading. Regenerate worker-configuration.d.ts with wrangler types. Document in the README how to create the staging database with wrangler d1 create and paste its id. Run tsc and the three dry runs, do not deploy, and open a pull request listing the files, the environment table and the dry-run output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that edits `wrangler.json` to add the two `env` blocks, `package.json` to add the per-environment scripts and the wider `check`, `src/index.ts` and `src/renderHtml.ts` to show the environment, the regenerated `worker-configuration.d.ts`, and the README with a staging section. `migrations/0001_create_comments_table.sql` is unchanged: the same migrations apply to each environment's database through the `--env` flag.

The description has a small table of environment, Worker name, database and the command that deploys it, the `wrangler d1 create` step a maintainer runs once, and the output of the three `wrangler deploy --dry-run` calls and `tsc`. The transcript at `GET /o/{org}/sessions/{id}/messages` keeps each command with its output, so a reviewer can see the bundle size and the resolved bindings per environment rather than take the pull request's word for it.

Before merging, a reviewer checks that the production `database_id` matches what is live, that the staging placeholder is unmistakable, and that no environment inherits a binding by accident. A follow-up on the same session can add `routes` or a custom domain per environment, or a GitHub Actions workflow that deploys staging on every push to `main` and production on a tag.

## Run it on every new Worker

A team with several Workers that all deploy straight to production runs this once per repository. From a script, send the body above to `POST /o/{org}/sessions` with each repository in `resources`, one run per repository, and a `request_id` that is a UUID v5 of the repository name so a retry is safe. Give the key a `webhook_url` and every run the key starts posts `run.completed` with `data.session_url` when its turn ends; a handler reads the pull request link from the session.

To keep environments honest afterwards, add an automation to the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and a prompt that runs `wrangler deploy --dry-run` for every environment on the pull request's branch and comments when a binding is added at the top level but missing from `env.staging` or `env.production`. The trigger clones that branch and places the event after the prompt, and the automation starts at most `max_runs_per_hour` runs in an hour.

## Why run it on Rush?

Environments in Wrangler are easy to add and easy to get silently wrong: a binding declared only at the top level vanishes in `--env staging`, and the first sign is a `TypeError` in a deployed Worker. The agent reads the actual bindings, redeclares each one per environment and runs a dry run for every environment in its own sandbox with `wrangler` already installed, so the pull request arrives with the failure mode already exercised.

Each `wrangler deploy --dry-run` and `tsc` and its output stay in the run's transcript, so the review is of a log rather than a promise, and the laptop that handed off the task is free while it happens. Several Workers can get the same environment layout at once, each in its own sandbox and its own pull request.

## Frequently asked questions

### Do bindings from the top level carry over into an environment?

No, and that is the main reason this is worth a careful pull request. `d1_databases`, `vars`, KV and R2 bindings must be declared again inside each `env` block or they are absent there. The agent redeclares every binding it finds and adds a dry run per environment to `check` so a future omission fails in CI.

### Will the agent create the staging database?

Only if the Project gives it a Cloudflare API token as a secret and the prompt asks. Otherwise it writes a marked placeholder `database_id`, documents `wrangler d1 create` and the follow-up `migrate:staging` script in the README, and leaves that one-time step to a maintainer. The dry runs validate the configuration shape without an account.

### What is the deployed Worker called?

With `--env staging`, Wrangler deploys the Worker under the top-level `name` with the environment appended, so `d1-template` becomes `d1-template-staging`, unless the `env.staging` block sets its own `name`. The agent leaves the production environment's name as the existing Worker so the live deployment does not move.

### Does local development change?

No. `wrangler dev` and the `dev` script keep using the top-level config and the local D1 seeded by `seedLocalD1`. To run locally against the staging bindings you pass `--env staging`, which the README now explains.

### Can the same migrations run against both databases?

Yes. The `migrations/` directory is shared and `wrangler d1 migrations apply DB --remote --env staging` applies it to whichever database `env.staging` binds as `DB`. That is why the agent keeps one binding name across environments instead of inventing `DB_STAGING`.

## More Cloudflare Workers jobs

- [Add WebSockets to a Cloudflare Worker with Durable Objects](https://getrush.ai/run/add-websockets/cloudflare-workers/)
- [Fix Cloudflare Worker Errors From Its Logs](https://getrush.ai/run/fix-cloudflare-worker-errors/cloudflare-workers/)
- [Turn Sentry Errors Into Fix Pull Requests for a Cloudflare Worker](https://getrush.ai/run/fix-sentry-errors/cloudflare-workers/)

## More jobs like this: Hand off a long task

- [Add Storybook to an Expo App](https://getrush.ai/run/add-storybook/expo/)
- [Set Up Storybook for Lit Web Components](https://getrush.ai/run/add-storybook/lit/)
- [Add Streaming Responses to a Hono API](https://getrush.ai/run/add-streaming-responses/hono/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
