secondsky/cloudflare-workers-dev-experience
Cloudflare Workers local development with Wrangler, Miniflare, hot reload, debugging. Use for project setup, wrangler.jsonc configuration, or encountering local dev, HMR, binding simulation errors.
npx skills add https://github.com/secondsky/claude-skills --skill cloudflare-workers-dev-experienceLocal development setup with Wrangler, Miniflare, and modern tooling.
# Create new project
bunx create-cloudflare@latest my-worker
# Or from scratch
mkdir my-worker && cd my-worker
bun init -y
bun add -d wrangler @cloudflare/workers-types
# Start local development
bunx wrangler dev
Scaffolding tools like bunx create-cloudflare download and execute remote code. Before running, follow supply chain security best practices:
npm config set ignore-scripts true (or Bun: disabled by default)socket package score npm <pkg> or use socket npm install <pkg> to check packagesLoad the dependency-upgrade skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "my-worker",
"main": "src/index.ts",
"compatibility_date": "2024-12-01",
// Development settings
"dev": {
"port": 8787,
"local_protocol": "http"
},
// Environment variables (non-secret)
"vars": {
"ENVIRONMENT": "development"
},
// Bindings
"kv_namespaces": [
{ "binding": "KV", "id": "abc123", "preview_id": "def456" }
],
"d1_databases": [
{ "binding": "DB", "database_id": "xyz789", "database_name": "my-db" }
],
"r2_buckets": [
{ "binding": "BUCKET", "bucket_name": "my-bucket" }
]
}
wrangler dev for local testing - Simulates Cloudflare runtime accuratelycompatibility_date - Controls runtime behavior, update quarterly@cloudflare/workers-types| Error | Symptom | Prevention |
|-------|---------|------------|
| Module not found | Import errors on deploy | Set "moduleResolution": "bundler" in tsconfig |
| Binding undefined | env.KV is undefined locally | Add preview_id to KV namespace config |
| HMR not working | Changes not reflecting | Check port conflicts, use --local flag |
| D1 schema mismatch | Queries fail locally | Run migrations on local DB |
| Type errors | Missing binding types | Generate types with wrangler types |
| CORS issues | Browser blocking requests | Add CORS headers in dev handler |
# Start dev server (recommended)
bunx wrangler dev
# With live reload
bunx wrangler dev --live-reload
# Remote mode (use actual Cloudflare services)
bunx wrangler dev --remote
# Specify environment
bunx wrangler dev --env staging
# Custom port
bunx wrangler dev --port 3000
tsconfig.json:
{
"compilerOptions": {
"target": "ES2022",
"module": "ES2022",
"moduleResolution": "bundler",
"lib": ["ES2022"],
"types": ["@cloudflare/workers-types"],
"strict": true,
"noEmit": true,
"skipLibCheck": true,
"allowSyntheticDefaultImports": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
{
"scripts": {
"dev": "wrangler dev",
"deploy": "wrangler deploy",
"deploy:staging": "wrangler deploy --env staging",
"deploy:production": "wrangler deploy --env production",
"test": "vitest",
"test:watch": "vitest --watch",
"type-check": "tsc --noEmit",
"lint": "eslint src/",
"types": "wrangler types",
"tail": "wrangler tail",
"db:migrate": "wrangler d1 migrations apply DB",
"db:studio": "wrangler d1 execute DB --local --command 'SELECT 1'"
}
}
// Development-only logging
export default {
async fetch(request: Request, env: Env): Promise<Response> {
if (env.ENVIRONMENT === 'development') {
console.log('Request:', request.method, request.url);
console.log('Headers:', Object.fromEntries(request.headers));
}
// Handler logic...
}
};
# Real-time logs from deployed worker
wrangler tail
# Filter by status
wrangler tail --status error
# Filter by method
wrangler tail --method POST
# JSON format for parsing
wrangler tail --format json
.vscode/launch.json:
{
"version": "0.2.0",
"configurations": [
{
"name": "Wrangler Dev",
"type": "node",
"request": "launch",
"runtimeExecutable": "bunx",
"runtimeArgs": ["wrangler", "dev", "--inspector-port", "9229"],
"skipFiles": ["<node_internals>/**"],
"sourceMaps": true
}
]
}
Load specific references based on the task:
references/local-development.md for complete setup guidereferences/wrangler-config.md for all configuration optionsreferences/debugging-tools.md for debugging techniques| Template | Purpose | Use When |
|----------|---------|----------|
| templates/wrangler-config.jsonc | Complete wrangler config | Starting new project |
| templates/dev-script.ts | Development utilities | Adding dev helpers |
| Script | Purpose | Command |
|--------|---------|---------|
| scripts/dev-setup.sh | Initialize dev environment | ./dev-setup.sh |
Take secondsky/cloudflare-workers-dev-experience from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.
The instructions reference npm.
Without those the skill loads but fails at the first command.