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

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