## TL;DR

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

```bash
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.
