Set up Cloudflare Workers with Hono routing, Vite plugin, and Static Assets using production-tested patterns.
Prevents 6 errors: export syntax, routing conflicts, HMR crashes, and Service Worker format confusion.
Use when: creating Workers projects, configuring Hono or Vite for Workers, deploying with Wrangler,
adding Static Assets with SPA fallback, or troubleshooting export syntax, API route conflicts, scheduled
handlers, or HMR race conditions.
Keywords: Cloudflare Workers, CF Workers, Hono, wrangler, Vite, Static Assets, @cloudflare/vite-plugin,
wrangler.jsonc, ES Module, run_worker_first, SPA fallback, API routes, serverless, edge computing,
"Cannot read properties of undefined", "Static Assets 404", "A hanging Promise was canceled",
"Handler does not export", deployment fails, routing not working, HMR crashes
Set up Cloudflare Workers with Hono routing, Vite plugin, and Static Assets using production-tested patterns.
Prevents 6 errors: export syntax, routing conflicts, HMR crashes, and Service Worker format confusion.
Use when: creating Workers projects, configuring Hono or Vite for Workers, deploying with Wrangler,
adding Static Assets with SPA fallback, or troubleshooting export syntax, API route conflicts, scheduled
handlers, or HMR race conditions.
Keywords: Cloudflare Workers, CF Workers, Hono, wrangler, Vite, Static Assets, @cloudflare/vite-plugin,
wrangler.jsonc, ES Module, run_worker_first, SPA fallback, API routes, serverless, edge computing,
"Cannot read properties of undefined", "Static Assets 404", "A hanging Promise was canceled",
"Handler does not export", deployment fails, routing not working, HMR crashes
vite: Latest version compatible with Cloudflare plugin
3. Configure Wrangler
Create or update wrangler.jsonc:
{"$schema":"node_modules/wrangler/config-schema.json","name":"my-worker","main":"src/index.ts","account_id":"YOUR_ACCOUNT_ID",// Find this in your Cloudflare dashboard (Workers & Pages -> Overview)."compatibility_date":"2025-10-11","observability":{"enabled":true},"assets":{"directory":"./public/","binding":"ASSETS","not_found_handling":"single-page-application","run_worker_first":["/api/*"]}}
# Generate TypeScript types for bindings
npm run cf-typegen
# Start local dev server (http://localhost:8787)
npm run dev
# Deploy to production
npm run deploy
Known Issues Prevention
This skill prevents 6 documented issues:
Issue #1: Export Syntax Error
Error: "Cannot read properties of undefined (reading 'map')"
Source: honojs/hono #3955Prevention: Use export default app (NOT { fetch: app.fetch })
Issue #2: Static Assets Routing Conflicts
Error: API routes return index.html instead of JSON
Source: workers-sdk #8879Prevention: Add "run_worker_first": ["/api/*"] to wrangler.jsonc
Issue #3: Scheduled/Cron Not Exported
Error: "Handler does not export a scheduled() function"
Source: honojs/vite-plugins #275Prevention: Use Module Worker format when needed:
Error: "A hanging Promise was canceled" during development
Source: workers-sdk #9518Prevention: Use @cloudflare/vite-plugin@1.13.13 or later
Issue #5: Static Assets Upload Race
Error: Non-deterministic deployment failures in CI/CD
Source: workers-sdk #7555Prevention: Use Wrangler 4.x+ with retry logic (fixed in recent versions)
Issue #6: Service Worker Format Confusion
Error: Using deprecated Service Worker format
Source: Cloudflare migration guide
Prevention: Always use ES Module format (shown in Step 1)
# Test GET endpoint
curl http://localhost:8787/api/hello
# Test POST endpoint
curl -X POST http://localhost:8787/api/echo \
-H "Content-Type: application/json" \
-d '{"test": "data"}'
Type Generation
npm run cf-typegen
Generates worker-configuration.d.ts with:
Binding types (KV, D1, R2, etc.)
Environment variable types
Auto-completes in your editor
Deployment
# Deploy to production
npm run deploy
# Deploy to specific environment
wrangler deploy --env staging
# Tail logs in production
wrangler tail# Check deployment status
wrangler deployments list
Complete Setup Checklist
Project scaffolded with npm create cloudflare@latest
