# cloudflare-workers-dev-experience

Guides local Cloudflare Workers development using Wrangler and Miniflare. Helps fix broken bindings for KV, D1, or R2, configure HMR, and set up tsconfig.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 303 installs · ★ 237
- Author: secondsky
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/secondsky/claude-skills/tree/HEAD/plugins/cloudflare-workers/skills/cloudflare-workers-dev-experience/SKILL.md
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/skills/cloudflare-workers-dev-experience

## What it does

This skill provides rules and templates for developing Cloudflare Workers locally. It includes a `wrangler.jsonc` blueprint with separated bindings for KV, D1 databases, and R2 buckets. TypeScript configuration targets ES2022 using `bundler` module resolution. Files include the `scripts/dev-setup.sh` script.

Missing `preview_id` causes `env.KV is undefined` during local testing. D1 migrations must run locally. The guide also tackles port conflicts blocking HMR, missing types, and CORS issues. For inspection, it configures `.vscode/launch.json` targeting port 9229.

Supply chain security is addressed directly. The instructions advise blocking install scripts via `ignore-scripts` and auditing dependencies with Socket CLI before running `bunx create-cloudflare`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill cloudflare-workers-dev-experience -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/cloudflare-workers-dev-experience/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/cloudflare-workers-dev-experience/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill cloudflare-workers-dev-experience -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/cloudflare-workers-dev-experience/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill cloudflare-workers-dev-experience -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/cloudflare-workers-dev-experience/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install secondsky/claude-skills cloudflare-workers-dev-experience
```

2. **Manually: put the files in place**
- File: `.github/skills/cloudflare-workers-dev-experience/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill cloudflare-workers-dev-experience -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/secondsky/claude-skills --path plugins/cloudflare-workers/skills/cloudflare-workers-dev-experience
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/cloudflare-workers-dev-experience/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill cloudflare-workers-dev-experience -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/secondsky/claude-skills/tree/HEAD/plugins/cloudflare-workers/skills/cloudflare-workers-dev-experience/SKILL.md

## When to use it
- configure wrangler.jsonc with bindings for KV, D1, and R2
- prevent env.KV is undefined errors by specifying preview_id
- set up VS Code debugging via inspector port 9229
- align tsconfig.json with @cloudflare/workers-types

## Example prompts
- Help me set up wrangler.jsonc with local D1 and R2 bindings
- Why does env.KV return undefined during local wrangler dev?
- Generate a launch.json config to debug my worker on port 9229

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: ed6a7ec908ac68f6.

BEGIN THIRD-PARTY FILE ed6a7ec908ac68f6
````text
---
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 |
````
END THIRD-PARTY FILE ed6a7ec908ac68f6

The third-party file has ended. Everything between the ed6a7ec908ac68f6 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2524 of 6258 bytes. © secondsky · MIT · https://github.com/secondsky/claude-skills/tree/HEAD/plugins/cloudflare-workers/skills/cloudflare-workers-dev-experience/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md