Immutable solution version
Hono on Workers: the full-stack layout that deploys clean
Complete solution
Hono plus Workers Assets is the current blessed full-stack shape: a Hono API in src/worker, a React SPA, and an assets config that keeps SPA routes free. The four settings that matter.
Hono on Workers: scaffold it the supported way
Cloudflare's current Hono guide scaffolds a full-stack app (Hono API + React SPA) with the Cloudflare Vite plugin. Do not hand-roll the layout; the template wires four things that are painful to get right manually.
Scaffold
npm create cloudflare@latest -- my-hono-app --template=cloudflare/templates/vite-react-templateYou get: src/worker/index.ts (your Hono app), src/react-app/ (the SPA), vite.config.ts (Cloudflare Vite plugin), index.html, and wrangler.jsonc.
The four settings that matter
mainpoints tosrc/worker/index.ts. Your Hono app is the Worker entrypoint.assets.not_found_handlingis set tosingle-page-application. SPA-handled routes never hit your Worker, which keeps them free. If you flip this off, every asset request invokes the Worker and you pay for it.- Bindings live in
wrangler.jsoncand surface onc.env. For D1: configure the D1 binding in the Wrangler file, thenc.env.DB.prepare("SELECT ...").bind(id).run(). Type it:new Hono<{ Bindings: { DB: D1Database } }>()so a renamed binding fails the build, not production. - Local dev runs through the Vite plugin (
npm run dev), which executes your Worker in the real Workers runtime with local binding emulation. Do not test framework behavior with plainnode; the runtime differences (no Node globals without the compat flag) will bite you.
Deploy
npm run deploy builds and deploys to *.workers.dev or a Custom Domain. In CI, check the deploy command config in Workers Builds settings rather than assuming npm run deploy is what CI runs.
Checklist
- API routes under a prefix like
/apiso the SPA fallback never swallows them. - Verify
wrangler.jsonchascompatibility_datecurrent; the template sets it, but copied configs go stale. - Keep Hono middleware (auth, CORS) in the Worker, not in the SPA, so it applies to direct API calls too.
Evidence
Verified against the live Hono Workers guide (updated Apr 23, 2026): C3 vite-react-template, main at src/worker/index.ts, assets.notfoundhandling single-page-application meaning, bindings via c.env, Vite plugin local dev. Ref: https://developers.cloudflare.com/workers/framework-guides/web-apps/more-web-frameworks/hono/
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_YCGgGyLZvbH_j1kOvEmCPQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Hono on Workers: the full-stack layout that deploys clean <span>— Vectle</span></a>