cloudflare-workers-dev-experience
/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.
- Author
- secondsky ↗
- Repository
- claude-skills ↗
- Licence
- MIT
- Last repository change
- 26.09.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 26.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/dev-setup.sh, templates/dev-script.ts
What it does and when to use it
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.
Original author description
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.
How it works
- Quick Start
- Secure Installation
- Essential wrangler.jsonc
- Critical Rules
- Top 6 Errors Prevented
- Local Development Workflow
- TypeScript Configuration
- Package.json Scripts
- Debugging
- When to Load References
SKILL.md preview
---
name: cloudflare-workers-dev-experience
description: 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.
license: MIT
---
# Cloudflare Workers Developer Experience
Local development setup with Wrangler, Miniflare, and modern tooling.
## Quick Start
```bash
# 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
```
## Secure Installation
Scaffolding tools like `bunx create-cloudflare` download and execute remote code. Before running, follow supply chain security best practices:
- **Block post-install scripts** — `npm config set ignore-scripts true` (or Bun: disabled by default)
- **Cooldown period** — Wait 7 days for new package versions to be vetted by the community
- **Audit before installing** — Run `socket package score npm <pkg>` or use `socket npm install <pkg>` to check packages
Load the `dependency-upgrade` skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.
## Essential wrangler.jsonc
```jsonc
{
"$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" }
]
}
```
## Critical Rules
1. **Always use `wrangler dev` for local testing** - Simulates Cloudflare runtime accurately
2. **Set `compatibility_date`** - Controls runtime behavior, update quarterly
3. **Use preview IDs for local dev** - Separate from production bindings
4. **Configure TypeScript properly** - Use `@cloudflare/workers-types`
5. **Enable source maps** - Better error stacks in development
## Top 6 Errors Prevented
| 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 |
## Local Development Workflow
```bash
# 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
```
## TypeScript Configuration
**tsconfig.json**:
```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"]
}
```
## Package.json Scripts
```json
{
"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'"
}
}
```
## Debugging
### Console Logging
```typescript
// 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...
}
};
```
### Using wrangler tail
```bash
# 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
```
### VS Code Debugging
**.vscode/launch.json**:
```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
}
]
}
```
## When to Load References
Load specific references based on the task:
- **Setting up project?** → Load `references/local-development.md` for complete setup guide
- **Configuring wrangler?** → Load `references/wrangler-config.md` for all configuration options
- **Debugging issues?** → Load `references/debugging-tools.md` for debugging techniques
## Templates
| Template | Purpose | Use When |
|----------|---------|----------|
| `templates/wrangler-config.jsonc` | Complete wrangler config | Starting new project |
| `templates/dev-script.ts` | Development utilities | Adding dev helpers |
## Scripts
| Script | Purpose | Command |
|--------|---------|---------|
| `scripts/dev-setup.sh` | Initialize dev environment | `./dev-setup.sh` |
## Resources
- Wrangler CLI: https://developers.cloudflare.com/workers/wrangler/
- Configuration: https://developers.cloudflare.com/workers/wrangler/configuration/
- Local Development: https://developers.cloudflare.com/workers/testing/local-development/
Files in this package (7)
- SKILL.md 6 KB
- references/debugging-tools.md 8 KB
- references/local-development.md 6 KB
- references/wrangler-config.md 6 KB
- scripts/dev-setup.sh 12 KB
- templates/dev-script.ts 12 KB
- templates/wrangler-config.jsonc 8 KB
Versions
The database has no other skills named cloudflare-workers-dev-experience.
Database snapshot: 13.11.2026 · package version 562219553ae8 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100cloudflare-workers-miniflare
Wraps Miniflare 3 (the official Cloudflare Workers simulator) and Wrangler dev for testing Workers locally. Covers Miniflare's getMiniflare() programmatic API (workerd-backed simulation matching prod), the wrangler dev local-mode (live-reload during dev), KV / Durable Objects /… - 100cloudflare-workers-miniflare
Use when Cloudflare Workers code needs tests locally: Miniflare 3 (workerd-backed), wrangler dev, emulated KV, Durable Objects, R2 and D1 bindings, and in-process tests with Vitest and @cloudflare/vitest-pool-workers. - 85workers-development
Run, inspect, and debug Cloudflare Workers during local development with cf dev, wrangler dev, or the Cloudflare Vite plugin, using Local Explorer to read and seed binding data and query local traces and logs. Also routes production debugging to Workers observability. Use for… - 100wrangler
Run or troubleshoot Wrangler CLI commands and configure Worker projects for local development, deployment, and Cloudflare resource management. Use when editing wrangler.jsonc, running wrangler commands, bumping compatibility dates, or maintaining a Cloudflare Workers deployment. - 100cloudflare-workers
Build and deploy edge functions with Cloudflare Workers and Wrangler. Use for APIs, cron jobs, and edge middleware. - 100cloudflare-workers
Build and deploy edge functions with Cloudflare Workers and Wrangler. Use for APIs, cron jobs, and edge middleware.