cloudflare-worker-builder
This skill scaffolds a complete Cloudflare Workers project with Hono routing, Vite development server, and static asset serving. Use it when users need to create a new Worker project, configure database or storage bindings like D1, R2, or KV, set up API routes alongside a frontend, or troubleshoot deployment issues such as export syntax errors, API route conflicts with SPA fallback, or hot module reloading problems.
git clone --depth 1 https://github.com/jezweb/claude-skills /tmp/cloudflare-worker-builder && cp -r /tmp/cloudflare-worker-builder/plugins/cloudflare/skills/cloudflare-worker-builder ~/.claude/skills/cloudflare-worker-builderSKILL.md
# 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 rolloutsHit the Cloudflare REST API directly for operations that wrangler and MCP can't handle well. Bulk DNS, custom hostnames, email routing, cache purge, WAF rules, redirect rules, zone settings, Worker routes, D1 cross-database queries, R2 bulk operations, KV bulk read/write, Vectorize queries, Queues, and fleet-wide resource audits. Produces curl commands or scripts. Triggers: 'cloudflare api', 'bulk dns', 'custom hostname', 'email routing', 'cache purge', 'waf rule', 'd1 query', 'r2 bucket', 'kv bulk', 'vectorize query', 'audit resources', 'fleet operation'.
Generate Drizzle ORM schemas for Cloudflare D1 databases with correct D1-specific patterns. Produces schema files, migration commands, type exports, and DATABASE_SCHEMA.md documentation. Handles D1 quirks: foreign keys always enforced, no native BOOLEAN/DATETIME types, 100 bound parameter limit, JSON stored as TEXT. Use when creating a new database, adding tables, or scaffolding a D1 data layer.
Cloudflare D1 migration workflow: generate with Drizzle, inspect SQL for gotchas, apply to local and remote, fix stuck migrations, handle partial failures. Use when running migrations, fixing migration errors, or setting up D1 schemas.
Generate database seed scripts with realistic sample data. Reads Drizzle schemas or SQL migrations, respects foreign key ordering, produces idempotent TypeScript or SQL seed files. Handles D1 batch limits, unique constraints, and domain-appropriate data. Use when populating dev/demo/test databases. Triggers: 'seed database', 'seed data', 'sample data', 'populate database', 'db seed', 'test data', 'demo data', 'generate fixtures'.
Scaffold Hono API routes for Cloudflare Workers. Produces route files, middleware, typed bindings, Zod validation, error handling, and API_ENDPOINTS.md documentation. Use after a project is set up with cloudflare-worker-builder or vite-flare-starter, when you need to add API routes, create endpoints, or generate API documentation.
Build a full-stack TanStack Start app on Cloudflare Workers from scratch — SSR, file-based routing, server functions, D1+Drizzle, better-auth, Tailwind v4+shadcn/ui. Use whenever the user mentions TanStack Start, asks to scaffold a full-stack Cloudflare app with SSR, wants an SSR dashboard, or asks for a React 19 + Cloudflare Workers app with file-based routing and server functions — even if they don't name TanStack Start specifically. No template repo — Claude generates every file fresh per project.
Scaffold a full-stack Cloudflare app from the vite-flare-starter template — React 19 + Hono + D1+Drizzle + better-auth + Tailwind v4+shadcn/ui + TanStack Query + R2 + Workers AI. Run setup.sh to clone, configure, and deploy. Use whenever the user wants a batteries-included Cloudflare full-stack app, vite-flare-starter scaffold, or a React + Cloudflare app with auth + database + Workers AI ready to go.
Generate AI images using Gemini or GPT APIs directly. Covers model selection (Gemini for scenes; GPT Image 2 for text rendering, batch variations, multi-reference compositing; GPT Image 1.5 for transparent icons), the 5-part prompting framework, API calling patterns, multi-turn editing, and quality assurance. Produces photorealistic scenes, icons, illustrations, OG images, posters, infographics, and product shots. Use when building websites that need images, creating marketing assets, or generating visual content. Triggers: 'generate image', 'ai image', 'create hero image', 'make an icon', 'generate illustration', 'create og image', 'poster', 'infographic', 'image variations', 'gpt-image-2', 'ai art', 'image generation'.