Deploying Workers

Overview

Cloudflare Workers supports two deployment methods:

Standard Deploy - Upload and immediately deploy to 100% of traffic
Gradual Rollouts - Upload versions and control traffic distribution

Standard Deployment

Deploy your Worker directly to production:

wrangler deploy

This command:

Bundles your Worker code
Uploads it to Cloudflare
Deploys immediately to 100% of traffic
Updates all configured routes and triggers

Deployment Options

wrangler deploy [script] [options]

Option	Description
`--name <name>`	Worker name (overrides config)
`--compatibility-date <date>`	Compatibility date for runtime
`--compatibility-flags <flags>`	Compatibility flags
`--minify`	Minify the Worker code
`--no-bundle`	Skip bundling step
`--dry-run`	Build without deploying
`--outdir <path>`	Output directory for build

Example Deployment

# Deploy with specific compatibility date
wrangler deploy --compatibility-date 2024-01-01

# Deploy with minification
wrangler deploy --minify

# Test build without deploying
wrangler deploy --dry-run

Gradual Rollouts (Versions)

Gradual rollouts allow you to deploy new versions incrementally by splitting traffic between multiple versions.

Upload a Version

First, upload your code as a new version without deploying:

wrangler versions upload

Upload the version

Create a new version with optional metadata:

wrangler versions upload \
  --tag "v1.2.0" \
  --message "Added new feature X"

Review version details

The upload returns a Version ID:

Worker Version ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Preview the version

If preview is enabled, access your version at:

https://<short-version-id>-<worker-name>.<subdomain>.workers.dev

Deploy Versions

Deploy one or more versions with traffic splitting:

wrangler versions deploy

The command will interactively prompt you to:

Select which versions to deploy
Specify traffic percentage for each version
Add an optional deployment message

Deploy Specific Versions

# Deploy single version to 100%
wrangler versions deploy --version-id <version-id>

# Deploy two versions with traffic split
wrangler versions deploy \
  --version-id <version-1> --percentage 80 \
  --version-id <version-2> --percentage 20

Shorthand Notation

Use the @ syntax for version-percentage pairs:

# Version 1 at 80%, Version 2 at 20%
wrangler versions deploy <version-1>@80 <version-2>@20

# Single version at 100%
wrangler versions deploy <version-id>@100

Version Upload Options

wrangler versions upload [script] [options]

Option	Description
`--tag <tag>`	Version tag for identification
`--message <message>`	Descriptive message for this version
`--preview-alias <alias>`	Named alias for preview URL
`--compatibility-date <date>`	Required: compatibility date
`--no-bundle`	Skip bundling
`--dry-run`	Build without uploading

A compatibility_date is required when uploading versions. Set it in your wrangler.json or pass it via --compatibility-date.

Traffic Splitting

When deploying multiple versions, traffic percentages must total 100%:

# Valid: 70% + 30% = 100%
wrangler versions deploy \
  <version-a>@70 \
  <version-b>@30

# Valid: Auto-distribute remaining traffic
wrangler versions deploy \
  --version-id <version-a> --percentage 60
  --version-id <version-b>  # Automatically receives 40%

Progressive Rollout Example

Deploy canary (5%)

wrangler versions deploy \
  <new-version>@5 \
  <stable-version>@95

Increase to 25%

wrangler versions deploy \
  <new-version>@25 \
  <stable-version>@75

Roll out to 100%

wrangler versions deploy <new-version>@100

Deployment Settings

Versioned Settings

These settings are part of each version:

Worker code and modules
Compatibility date and flags
Bindings (KV, R2, D1, Durable Objects, etc.)
Environment variables
Secrets
Placement configuration
Cache settings

Non-Versioned Settings

These settings apply globally and are not version-specific:

Logpush configuration
Tail consumers
Streaming tail consumers
Observability settings

Non-versioned settings are synced during wrangler versions deploy:

// From versions/deploy.ts:559-624
const maybeUndefinedSettings = {
  logpush: config.logpush,
  tail_consumers: config.tail_consumers,
  streaming_tail_consumers: config.streaming_tail_consumers,
  observability: config.observability,
};

Changes to non-versioned settings take effect after running wrangler versions deploy.

Triggers and Routes

Routes, custom domains, and cron schedules are managed separately:

# Deploy trigger changes
wrangler triggers deploy

This is separate from version deployments to prevent accidental route changes during gradual rollouts.

Deployment Workflow Comparison

Standard Deploy

# One command to upload and deploy
wrangler deploy

✅ Simple and fast
✅ Automatic trigger updates
❌ No gradual rollout
❌ Immediate 100% traffic

Gradual Rollout

# Separate upload and deploy steps
wrangler versions upload
wrangler versions deploy

✅ Traffic splitting
✅ Safe incremental rollouts
✅ Version previews
❌ More steps required
❌ Separate trigger management

Best Practices

Use Versions for Production - Gradual rollouts reduce risk
Add Metadata - Use --tag and --message to track versions
Test in Preview - Verify versions before deploying
Monitor Metrics - Watch error rates during rollouts
Keep Stable Versions - Maintain a known-good version for rollback

Next Steps

Version Management

List and view version details

Rollbacks

Roll back to previous versions

Secrets

Manage Worker secrets

Get Started

Core Tools

Development

Deployment

Platform Features

Advanced

Overview

Standard Deployment

Deployment Options

Example Deployment

Gradual Rollouts (Versions)

Upload a Version

Deploy Versions

Deploy Specific Versions

Shorthand Notation

Version Upload Options

Traffic Splitting

Progressive Rollout Example

Deployment Settings

Versioned Settings

Non-Versioned Settings

Triggers and Routes

Deployment Workflow Comparison

Standard Deploy

Gradual Rollout

Best Practices

Next Steps

Version Management

Rollbacks

Secrets

​Overview

​Standard Deployment

​Deployment Options

​Example Deployment

​Gradual Rollouts (Versions)

​Upload a Version

​Deploy Versions

​Deploy Specific Versions

​Shorthand Notation

​Version Upload Options

​Traffic Splitting

​Progressive Rollout Example

​Deployment Settings

​Versioned Settings

​Non-Versioned Settings

​Triggers and Routes

​Deployment Workflow Comparison

​Standard Deploy

​Gradual Rollout

​Best Practices

​Next Steps

Version Management

Rollbacks

Secrets

Overview

Standard Deployment

Deployment Options

Example Deployment

Gradual Rollouts (Versions)

Upload a Version

Deploy Versions

Deploy Specific Versions

Shorthand Notation

Version Upload Options

Traffic Splitting

Progressive Rollout Example

Deployment Settings

Versioned Settings

Non-Versioned Settings

Triggers and Routes

Deployment Workflow Comparison

Standard Deploy

Gradual Rollout

Best Practices

Next Steps