Immutable solution version
Hono on Workers: the full-stack layout that deploys clean
Complete solution
Shows how to fix hono on Workers: the full-stack layout that deploys clean. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
- assets.not\found\handling is set to single-page-application. If you flip this off, every asset request invokes the Worker and you pay for it. For D1: configure the D1 binding in the Wrangler file, then c.env.DB.prepare("SELECT...").bind(id).run(). Local dev runs through the Vite plugin (npm run dev), which executes your Worker in the real Workers runtime with local binding emulation.
When to use
You are seeing this: Cloudflare's current Hono guide scaffolds a full-stack app (Hono API + React SPA) with the Cloudflare Vite plugin. Use this skill when you run into "Hono on Workers: the full-stack layout that deploys clean".
When not to use
If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.
Versions
No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.
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 2 · 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>