---
name: Cloudflare Worker Builder
slug: cloudflare-worker-builder
category: DevOps
description: Cloudflare Worker Builder scaffolds and deploys Cloudflare Worker projects with Hono, Vite, and Static Assets. Use it to set up bindings, route APIs, and troubleshoot export or deployment issues.
github: "https://github.com/jezweb/claude-skills/tree/main/plugins/cloudflare/skills/cloudflare-worker-builder"
language: Python
stars: 974
forks: 102
install: "npx degit https://github.com/jezweb/claude-skills/tree/main/plugins/cloudflare/skills/cloudflare-worker-builder ~/.claude/skills/cloudflare-worker-builder"
installs_to: ~/.claude/skills/cloudflare-worker-builder
source_path: plugins/cloudflare/skills/cloudflare-worker-builder/SKILL.md
collection_size: 25
category_size: 798
collection_url: "https://dirskills.com/collections/jezweb/claude-skills"
added: 2026-08-21T05:14:46.948Z
last_synced: 2026-08-21T05:14:46.948Z
canonical_url: "https://dirskills.com/skills/cloudflare-worker-builder"
---

# Cloudflare Worker Builder

Cloudflare Worker Builder scaffolds and deploys Cloudflare Worker projects with Hono, Vite, and Static Assets. Use it to set up bindings, route APIs, and troubleshoot export or deployment issues.

**Install:**

```bash
npx degit https://github.com/jezweb/claude-skills/tree/main/plugins/cloudflare/skills/cloudflare-worker-builder ~/.claude/skills/cloudflare-worker-builder
```

## README

# Cloudflare Worker Builder

Scaffold a working Cloudflare Worker project from a brief description. Produces a deployable project with Hono routing, Vite dev server, and Static Assets.

## Workflow

### Step 1: Understand the Project

Ask about the project to choose the right bindings and structure:

- What does the app do? (API only, SPA + API, landing page)
- What data storage? (D1 database, R2 files, KV cache, none)
- Auth needed? (Clerk, better-auth, none)
- Custom domain or workers.dev subdomain?

A brief like "todo app with database" is enough to proceed.

### Step 2: Scaffold the Project

```bash
npm create cloudflare@latest my-worker -- --type hello-world --ts --git --deploy false --framework none
cd my-worker
npm install hono
npm install -D @cloudflare/vite-plugin vite
```

Copy and customise the asset files from this skill's `assets/` directory:
- `wrangler.jsonc` — Worker configuration
- `vite.config.ts` — Vite + Cloudflare plugin
- `src/index.ts` — Hono app with Static Assets fallback
- `package.json` — Scripts and dependencies
- `tsconfig.json` — TypeScript config
- `public/index.html` — SPA entry point

### Step 3: Configure Bindings

Add bindings to `wrangler.jsonc` based on project needs. Wrangler 4.45+ auto-provisions resources on first deploy — always specify explicit names:

```jsonc
{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-11-11",
  "assets": {
    "directory": "./public/",
    "binding": "ASSETS",
    "not_found_handling": "single-page-application",
    "run_worker_first": ["/api/*"]
  },
  // Add as needed:
  "d1_databases": [{ "binding": "DB", "database_name": "my-app-db" }],
  "r2_buckets": [{ "binding": "STORAGE", "bucket_name": "my-app-files" }],
  "kv_namespaces": [{ "binding": "CACHE", "title": "my-app-cache" }]
}
```

### Step 4: Deploy

```bash
npm run dev           # Local dev at http://localhost:8787
wrangler deploy       # Production deploy
```

---

## Critical Patterns

### Export Syntax

```typescript
// CORRECT — use this pattern
export default app

// WRONG — causes "Cannot read properties of undefined"
export default { fetch: app.fetch }
```

Source: [honojs/hono #3955](https://github.com/honojs/hono/issues/3955)

### Static Assets + API Routes

Without `run_worker_first`, SPA fallback intercepts API routes and returns `index.html` instead of JSON:

```jsonc
"assets": {
  "not_found_handling": "single-page-application",
  "run_worker_first": ["/api/*"]  // CRITICAL
}
```

Source: [workers-sdk #8879](https://github.com/cloudflare/workers-sdk/issues/8879)

### Vite Config

```typescript
import { defineConfig } from 'vite'
import { cloudflare } from '@cloudflare/vite-plugin'

export default defineConfig({ plugins: [cloudflare()] })
```

Always set the `main` field in wrangler.jsonc — the Vite plugin needs it.

### Scheduled/Cron Handlers

When adding cron triggers, switch to explicit export:

```typescript
export default {
  fetch: app.fetch,
  scheduled: async (event, env, ctx) => { /* ... */ }
}
```

---

## Reference Files

Read these for detailed troubleshooting:

- `references/common-issues.md` — 10 documented issues with sources and fixes
- `references/architecture.md` — Route priority, caching, Workers RPC
- `references/deployment.md` — CI/CD, auto-provisioning, gradual rollouts