Deployment management

By default, a new version is created and immediately deployed to 100% of traffic when you use any of the following:

• wrangler deploy
• Workers Builds
• The Workers Script Upload API

You can separate these steps so that uploading a version and deploying it are independent actions. This lets you control exactly when a new version goes live.

Upload a version without deploying

Via Wrangler

Use the wrangler versions upload command:

npm yarn pnpm

npx wrangler versions upload

yarn wrangler versions upload

pnpm wrangler versions upload

Note

Wrangler versions before 3.73.0 require you to specify a --x-versions flag.

Note

To apply changes to a Worker's triggers (routes, domains, or cron triggers), use the wrangler triggers deploy command.

Via the Cloudflare dashboard

1. In the Cloudflare dashboard, go to the Workers & Pages page.

   Go to Workers & Pages

2. Select your Worker > Edit code.

3. Make your changes, then select the down arrow next to Deploy > Save.

Note

New versions are not created when you make changes to resources connected to your Worker. For example, if two Workers (Worker A and Worker B) are connected via a service binding, changing the code of Worker B will not create a new version of Worker A. Changes to the service binding configuration (such as deleting the binding or updating the environment it points to) on Worker A will also not create a new version of Worker B.

Deploy an uploaded version

Once you have uploaded a version, you can create a deployment that routes traffic to it.

Via Wrangler

Use the wrangler versions deploy command and follow the interactive prompts to select the version and set it to 100%:

npm yarn pnpm

npx wrangler versions deploy

yarn wrangler versions deploy

pnpm wrangler versions deploy

You can also set the traffic percentage to less than 100% to start a gradual deployment.

Via the Cloudflare dashboard

1. In the Cloudflare dashboard, go to the Workers & Pages page.

   Go to Workers & Pages

2. Select your Worker > Deployments.

3. Select Promote deployment and choose the version you want to deploy.

Via Infrastructure as Code

You can also create versions and deployments directly with the API, library SDKs, and Terraform. Refer to Infrastructure as Code for examples.

Limits

Deployments limit

You can only create a deployment with the last 100 uploaded versions of your Worker.

First upload

You must use C3 or wrangler deploy the first time you create a new Workers project. Using wrangler versions upload the first time you upload a Worker will fail.

Service worker syntax

Service worker syntax is not supported for versions that are uploaded through wrangler versions upload. You must use ES modules format.

Refer to Migrate from Service Workers to ES modules to learn how to migrate your Workers from the service worker format to the ES modules format.

Durable Object migrations

Uploading a version that changes Durable Object class lifecycle is not supported. This applies to both the declarative exports field and the legacy migrations array - any change that creates, deletes, renames, or transfers a Durable Object class must be applied through wrangler deploy.