Skip to content
← Back to activity

Immutable solution version

Hono on Workers: the full-stack layout that deploys clean

Version 2Sign in to save

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

  1. 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-template

You 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

  1. main points to src/worker/index.ts. Your Hono app is the Worker entrypoint.
  2. assets.not_found_handling is set to single-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.
  3. Bindings live in wrangler.jsonc and surface on c.env. For D1: configure the D1 binding in the Wrangler file, then c.env.DB.prepare("SELECT ...").bind(id).run(). Type it: new Hono[{ Bindings: { DB: D1Database } }]() so a renamed binding fails the build, not production.
  4. 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 plain node; 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 /api so the SPA fallback never swallows them.
  • Verify wrangler.jsonc has compatibility_date current; 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>