Wrangler is the official command-line tool for developing, testing, and deploying Cloudflare Workers. It provides a complete development workflow from local development to production deployment.
Current Version: 4.69.0Wrangler requires Node.js 20.0.0 or higher and is supported on macOS 13.5+, Windows 11, and Linux distros with glib 2.35+.
Installation Install Wrangler globally or as a project dependency:
# Install globally npm install -g wrangler # Or as a dev dependency npm install --save-dev wrangler
Verify installation:
Quick Start Initialize a new Worker project:
wrangler init my-worker -y
This creates a new Worker with:
A wrangler.jsonc configuration file
A basic Worker script in src/index.ts
TypeScript configuration
Package.json with necessary dependencies
Core Features
Local Development Run your Worker locally with live reloading and Chrome DevTools debugging
One-Click Deploy Deploy to Cloudflare’s global network with a single command
Resource Management Create and manage KV namespaces, R2 buckets, D1 databases, and more
Secrets Management Securely manage environment variables and secrets
Essential Commands Development Start a local development server with live reloading:
The dev server provides:
Hot module reloading for instant updates
Chrome DevTools integration for debugging
Local bindings simulation (KV, R2, D1, Durable Objects)
Request/response inspection
Access DevTools by visiting chrome://inspect in a Chromium-based browser and clicking “inspect” next to your Worker.
Deployment Deploy your Worker to production:
Deploy to a specific environment:
wrangler deploy --env production
By default, Workers are deployed to <worker-name>.<subdomain>.workers.dev. You can add custom domains in the Cloudflare dashboard.
Tail Logs Stream live logs from your deployed Worker:
Filter logs by status:
wrangler tail --status error
Configuration Wrangler uses a wrangler.jsonc, wrangler.json, or wrangler.toml file for configuration. The JSON format is recommended for better IDE support.
Basic Configuration { "$schema" : "node_modules/wrangler/config-schema.json" , "name" : "my-worker" , "main" : "./src/index.ts" , "compatibility_date" : "2024-03-01" }
Configuration with Bindings { "$schema" : "node_modules/wrangler/config-schema.json" , "name" : "my-worker" , "main" : "./src/index.ts" , "compatibility_date" : "2024-03-01" , "kv_namespaces" : [ { "binding" : "MY_KV" , "id" : "abc123..." } ], "r2_buckets" : [ { "binding" : "MY_BUCKET" , "bucket_name" : "my-bucket" } ], "d1_databases" : [ { "binding" : "DB" , "database_name" : "my-db" , "database_id" : "xyz789..." } ], "vars" : { "API_URL" : "https://api.example.com" } }
Multi-Environment Configuration { "$schema" : "node_modules/wrangler/config-schema.json" , "name" : "my-worker" , "main" : "./src/index.ts" , "compatibility_date" : "2024-03-01" , "vars" : { "ENVIRONMENT" : "development" }, "env" : { "staging" : { "vars" : { "ENVIRONMENT" : "staging" } }, "production" : { "vars" : { "ENVIRONMENT" : "production" }, "routes" : [ { "pattern" : "example.com/*" , "zone_name" : "example.com" } ] } } }
Resource Management KV Namespaces Create a KV namespace:
wrangler kv namespace create MY_KV
List namespaces:
wrangler kv namespace list
Manage keys:
# Put a key wrangler kv key put --binding MY_KV "my-key" "my-value" # Get a key wrangler kv key get --binding MY_KV "my-key" # Delete a key wrangler kv key delete --binding MY_KV "my-key" # List all keys wrangler kv key list --binding MY_KV
R2 Buckets Create an R2 bucket:
wrangler r2 bucket create my-bucket
List buckets:
Manage objects:
# Put an object wrangler r2 object put my-bucket/file.txt --file ./local-file.txt # Get an object wrangler r2 object get my-bucket/file.txt # Delete an object wrangler r2 object delete my-bucket/file.txt
D1 Databases Create a D1 database:
wrangler d1 create my-database
Execute SQL:
wrangler d1 execute my-database --command "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"
Run migrations:
wrangler d1 migrations apply my-database
Queues Create a queue:
wrangler queues create my-queue
List queues:
Secrets Management Secrets are encrypted environment variables that aren’t visible in your code.
Add a secret:
wrangler secret put API_KEY # You'll be prompted to enter the value
List secrets:
Delete a secret:
wrangler secret delete API_KEY
Bulk upload secrets from a file:
wrangler secret bulk .env.production
Deployments & Versions Gradual Rollouts Wrangler supports gradual rollouts to test changes with a percentage of traffic:
# Upload a new version without deploying wrangler versions upload # Deploy with traffic split wrangler versions deploy --percentage 10
Rollback Quickly rollback to a previous deployment:
View deployment history:
wrangler deployments list
Advanced Features Durable Objects Generate a Durable Object class:
wrangler init my-do --type durable-object
Manage dispatch namespaces:
# Create a namespace wrangler dispatch-namespace create my-namespace # List namespaces wrangler dispatch-namespace list
Analytics Engine Query analytics data:
wrangler analytics-engine sql --dataset my-dataset --query "SELECT * FROM my-dataset LIMIT 10"
Workflows Manage Cloudflare Workflows:
# List workflow instances wrangler workflows list # Describe a workflow wrangler workflows describe my-workflow # Trigger a workflow wrangler workflows trigger my-workflow
Programmatic API Wrangler can be used programmatically in Node.js applications:
import { unstable_dev } from "wrangler" ; // Start a dev server programmatically const worker = await unstable_dev ( "src/index.ts" , { experimental: { disableExperimentalWarning: true }, }); // Send requests const response = await worker . fetch ( "http://localhost" ); console . log ( await response . text ()); // Stop the server await worker . stop ();
Debugging Wrangler integrates with Chrome DevTools for debugging:
Start dev server with inspector:
wrangler dev --inspector-port 9229
Open chrome://inspect in Chrome
Click “inspect” next to your Worker
Use breakpoints, console, and profiler
Verbose Logging Enable verbose output for troubleshooting:
Configuration Schema Wrangler provides a JSON schema for IDE autocompletion:
{ "$schema" : "node_modules/wrangler/config-schema.json" , // Your IDE will now provide autocomplete and validation }
Common Workflows Local Development to Production
Initialize project:
Develop locally:
Create resources: wrangler kv namespace create MY_KV wrangler d1 create my-db
Update configuration: { "kv_namespaces" : [ { "binding" : "MY_KV" , "id" : "..." } ], "d1_databases" : [ { "binding" : "DB" , "database_id" : "..." } ] }
Deploy:
Monitor:
Testing with Different Bindings Test with local bindings during development:
# Development uses local simulator wrangler dev # Preview with production bindings wrangler dev --remote
Using --remote runs your code on Cloudflare’s network with production bindings. Use carefully to avoid unintended changes.
Best Practices
TypeScript provides better IDE support and catches errors before deployment: wrangler init my-worker --type typescript
Version Control Configuration
Commit wrangler.jsonc but use secrets for sensitive data: # Good: Use secrets for API keys wrangler secret put API_KEY # Bad: Don't put secrets in wrangler.jsonc
Environment-Specific Configuration
Use environments for different deployment targets: { "env" : { "staging" : { ... }, "production" : { ... } } }
Always test locally before deploying: wrangler dev # Test locally first wrangler deploy --dry-run # Validate without deploying wrangler deploy # Deploy to production
Troubleshooting Common Issues Authentication errors: # Login to Cloudflare wrangler login # Or use API token export CLOUDFLARE_API_TOKEN = your-token
Build errors: # Clear cache and rebuild rm -rf node_modules/.cache wrangler deploy
Port already in use: # Use a different port wrangler dev --port 8788
Additional Resources Miniflare Local Workers simulator powered by workerd
Create Cloudflare Scaffold new Cloudflare projects