Wrangler

Wrangler is a community skill for managing Cloudflare Workers projects using the Wrangler CLI, covering project scaffolding, local development, deployment, binding configuration, and environment management for edge application workflows.

What Is This?

Overview

Wrangler provides patterns for developing and deploying Cloudflare Workers using the official CLI tool. It covers project scaffolding with templates for Workers, Pages, and Durable Object projects, local development with hot reloading and service binding simulation using wrangler dev, deployment workflows for publishing Workers to Cloudflare's edge network with environment targeting, binding configuration for KV namespaces, D1 databases, R2 buckets, and Durable Objects in wrangler.toml, and environment management with staging and production configurations for multi-stage deployment pipelines. The skill enables developers to manage the full lifecycle of Cloudflare Workers from creation to production deployment, reducing manual steps and ensuring consistent, repeatable deployments across all environments.

Who Should Use This

This skill serves developers building serverless applications on Cloudflare Workers, teams managing multi-environment deployment pipelines for edge functions, and engineers configuring service bindings and storage resources for Workers projects. It is particularly useful for teams transitioning from dashboard-based deployments to fully automated CLI-driven workflows.

Why Use It?

Problems It Solves

Manual Workers deployment through the dashboard is error-prone and not reproducible. Local development without simulated bindings makes testing Workers with KV and D1 difficult. Environment-specific configuration for staging and production needs structured management. Service binding setup across multiple resources requires precise toml configuration. Without a consistent CLI workflow, configuration drift between environments becomes a common source of production incidents.

Core Highlights

wrangler dev provides local development with binding simulation and hot reload. wrangler deploy publishes Workers with environment targeting. wrangler.toml centralizes binding configuration for all resources. wrangler d1 and wrangler kv manage storage resources from the command line.

How to Use It?

Basic Usage

name = "my-api"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[[kv_namespaces]]
binding = "CACHE"
id = "abc123"

[[ d1_databases ]]
binding = "DB"
database_name = "my-db"
database_id = "def456"

[[r2_buckets]]
binding = "STORAGE"
bucket_name = "my-bucket"

[env.staging]
name = "my-api-staging"
[[env.staging.kv_namespaces]]
binding = "CACHE"
id = "staging-abc"

[env.production]
name = "my-api-prod"
[[env.production.kv_namespaces]]
binding = "CACHE"
id = "prod-abc"

Real-World Examples

#!/bin/bash

npx wrangler init my-api \\
  --type worker --ts

npx wrangler dev --local

npx wrangler d1 create my-db

npx wrangler d1 migrations \\
  apply my-db --local

npx wrangler kv key put \\
  --binding CACHE \\
  "config" '{"version":1}'

npx wrangler deploy \\
  --env staging

npx wrangler deploy \\
  --env production

npx wrangler tail \\
  --env production

npx wrangler d1 migrations \\
  apply my-db --remote

Advanced Tips

Use wrangler dev --remote to test against real Cloudflare bindings when local simulation is insufficient, particularly for Durable Objects or Queues that behave differently in the local runtime. Configure CI/CD pipelines with CLOUDFLARE_API_TOKEN for automated deployment on merge, storing the token as an encrypted secret in your pipeline provider. Use wrangler tail to stream real-time logs from production Workers for debugging live issues, and combine it with grep to filter for specific error patterns. Configure wrangler.toml compatibility flags to opt into new runtime features while maintaining backward compatibility.

When to Use It?

Use Cases

Build a CI/CD pipeline that deploys Workers to staging on pull request and production on merge. Set up local development for a Worker that uses KV, D1, and R2 bindings with simulated storage. Manage D1 database migrations across development and production environments. Use wrangler secret bulk to populate environment-specific secrets during automated deployments without exposing values in configuration files.

Related Topics

Cloudflare Workers, edge deployment, serverless CLI, toml configuration, and CI/CD pipelines.

Important Notes

Requirements

Node.js 16 or later for running the Wrangler CLI. Cloudflare account with Workers access for deployment. API token with Workers permissions for CI/CD automation.

Usage Recommendations

Do: use environment-specific configuration in wrangler.toml for staging and production separation. Run D1 migrations locally first with --local before applying to remote databases. Pin Wrangler versions in CI to prevent unexpected behavior from CLI updates.

Don't: commit API tokens or account IDs to the repository when using CI/CD deployment. Skip local testing with wrangler dev before deploying to production. Use the same KV namespace IDs across staging and production environments.

Limitations

Local development simulation does not perfectly replicate Cloudflare's edge runtime behavior. Some bindings like Queues and Hyperdrive have limited local simulation support. Wrangler CLI updates may introduce breaking changes to configuration format. Deployment previews are limited to Workers without Durable Object bindings in some configurations. Secret management through wrangler secret requires separate commands per environment.