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 rolloutsGenerate 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'.
Generate complete user documentation for a web app with screenshots. Browses the app via browser automation, screenshots every screen, and produces a structured user guide with step-by-step instructions, annotated screenshots, workflow diagrams, and reference tables. Supports quick (key screens), standard (all pages), thorough (every state and flow), and exhaustive (publishable documentation suite). Triggers: 'document the app', 'user guide', 'app documentation', 'screenshot docs', 'generate user docs', 'help docs', 'how-to guide', 'write the docs'.
Australian business English for professional writing — warm, direct, EN-AU spelling (colour, organise, centre), no filler words. Use whenever the user is writing for an Australian audience: emails, chat messages, proposals, client communications, blog posts, web copy, or any business writing. Apply to drafting, editing, and tone-checking professional text.
Write compelling award submissions, grant applications, and competition entries. Maps achievements to selection criteria using evidence-based narratives. Use whenever the user is applying for a business award (Telstra, chamber of commerce, industry awards), a grant, a competition, or any submission demonstrating merit against defined criteria.
Get a second opinion from leading AI models on code, architecture, strategy, prompting, or anything. Queries models via OpenRouter, Gemini, or OpenAI APIs. Supports single opinion, multi-model consensus, and devil's advocate patterns. Use whenever the user says 'brains trust', 'second opinion', 'ask gemini', 'ask gpt', 'peer review', 'consult another model', 'challenge this', or 'devil's advocate'.
Hit 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'.
Run an independent code review using the OpenAI Codex CLI in headless mode. Gets a second opinion from a different model family (the current Codex models) on recent changes, a PR, a commit, or the whole app — covering bugs, regressions, security, data consistency, UX/state bugs, performance risks, and testing gaps. Saves a severity-prioritised report to .jez/reviews/. Triggers: 'codex review', 'review with codex', 'independent code review', 'what does codex think', 'get codex to review'.
Generate complete, accessible colour palettes from a single brand hex. Produces 11-shade scale (50-950), semantic tokens, dark mode variants, Tailwind v4 CSS output, WCAG contrast checks. Use whenever the user supplies a brand hex and asks for a palette, mentions setting up a design system, wants Tailwind theme colours from a brand colour, or asks to check colour accessibility / contrast.