cloudflare-worker-base_skill

Overview

This skill sets up a production-ready Cloudflare Workers base using Hono routing, the Cloudflare Vite plugin, and Static Assets with SPA fallback. It encodes proven patterns to prevent common runtime and deployment errors, including export issues, routing conflicts, HMR race conditions, asset mismatch during gradual rollouts, and free-tier 429s. Use it to scaffold, configure, or harden Workers projects for reliable edge deployments.

How this skill works

The skill provides a minimal scaffold, example configuration files (wrangler.jsonc, vite.config.ts, src/index.ts) and clear rules for export format and asset routing. It enforces ES Module exports (export default app), configures run_worker_first only for API routes, and recommends Vite plugin versions and Wrangler releases that avoid HMR and upload races. It also documents mitigations for gradual-rollout asset mismatches and billing-related 429s when using run_worker_first.

When to use it

• Creating a new Cloudflare Workers project with Hono and Vite
• Configuring Static Assets with SPA fallback and API routes
• Deploying with Wrangler and auto-provisioned bindings (R2/D1/KV)
• Troubleshooting export syntax errors or missing scheduled handlers
• Preventing HMR race conditions and CI/CD static asset upload failures

Best practices

• Always export the Hono app as default (export default app) to avoid undefined export errors
• Set run_worker_first only for essential API patterns (e.g. "/api/*") to prevent SPA fallback from intercepting APIs
• Pin @cloudflare/vite-plugin and Vite to versions known to fix HMR issues and upload races
• Prefer instant cutover deployments for fingerprinted static assets or implement version-aware routing if gradual rollouts are required
• Limit run_worker_first patterns or upgrade to a paid Workers plan to avoid free-tier 429s

Example use cases

• Quickly scaffold a Worker with Hono and Vite using included templates and config snippets
• Add Static Assets with SPA fallback while keeping /api/* served by the Worker
• Deploy an app that uses R2, D1, or KV and rely on Wrangler auto-provisioning
• Resolve errors like "Cannot read properties of undefined" or "Handler does not export a scheduled() function"
• Avoid HMR crashes during local development by using recommended plugin versions