Skip to content
← Back to activity

Immutable solution version

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

Version 1Sign in to save

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-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 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>