Running on Hono?

Hono on Workers, Bun or Deno misbehaving? We sort it out.

Hono is the framework most teams reach for when the server has to run on Cloudflare Workers, Bun, Deno and Node from the same codebase. The sharp edges are predictable: middleware order that silently breaks a cookie, runtime adapters that leak subtle differences into handlers, RPC types that drift between client and server. We work through the routes, the adapters and the types until the app behaves the same everywhere it runs.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

hono.log

still failing

What it is

Hono at a glance

Hono is a small, fast web framework written in TypeScript that runs across multiple JavaScript runtimes: Cloudflare Workers and Pages, Bun, Deno, Node.js, Fastly Compute, AWS Lambda and more. It is designed around the standard Web Request and Response objects, which is why the same application can move between runtimes with minimal changes.

The library ships a Hono-specific router (several router flavours are available with different performance trade-offs), middleware primitives, a JSX implementation for server-side rendering, and a typed RPC pattern that gives the client end-to-end type safety against the server's route definitions. It is MIT licensed and is one of the fastest-growing backend frameworks in the JavaScript ecosystem.

Type
Lightweight multi-runtime web framework for JavaScript and TypeScript
First released
2022
License
MIT
Maintained by
Hono core team and community contributors
Typically used for
Edge APIs on Cloudflare Workers, Bun and Deno services, serverless endpoints, lightweight gateways

The honest version

Hono pros and cons

No technology is all upside. This is where Hono earns its place and where it tends to cause trouble.

Where Hono is strong

  • Runs anywhere Web Standards doCloudflare Workers, Bun, Deno, Node, Lambda, Fastly and Vercel Edge share the same application code, with runtime-specific adapters that are thin and legible.
  • Built for the edgeThe Request and Response model matches what Workers and other edge runtimes actually expose, so there is no shim layer pretending to be Express under the hood.
  • Typed RPC between client and serverThe hc client gives the client end-to-end TypeScript types inferred from the server's route definitions, which replaces most of the ad-hoc fetch wrappers teams otherwise write.
  • Tiny footprintThe framework bundles to a few kilobytes, which matters on Workers where every byte counts against the startup budget.
  • Reasonable middleware modelHooks around requests, responses and errors are explicit and composable, and the standard set (cors, jwt, basic-auth, logger, etag) covers most real needs.
  • Good ergonomics for JSX responsesReturning JSX from a handler for server-side HTML works without a separate templating layer, which pairs well with HTMX and similar workflows.

Where Hono bites

  • Middleware order mistakes bite quietlyPutting cors after auth, or logging after an error handler that short-circuits, produces behaviour that looks correct in local testing and fails on the edge.
  • Runtime differences still leakReadableStream, timers, crypto and cookie handling all differ slightly between Workers, Bun, Deno and Node. Code that works on one can break on another without warning.
  • RPC types drift under refactorsThe typed client depends on importing the server's types; a large refactor can produce type errors that are really stale imports rather than real bugs.
  • Ecosystem is younger than Express or FastifyMost of what you need exists, and the gap keeps closing, but you will hit occasional missing middleware or thin documentation on an edge case.
  • Debugging on Workers is awkwardwrangler dev is good, wrangler tail is useful, and both still have the limits of a remote edge runtime compared to local debugging on Node.
  • Validation picks need thoughtHono integrates with Zod, Valibot, TypeBox and others through adapters. Picking one and sticking to it matters, because schemas do not cross-validate between libraries.

Sound familiar?

Common Hono problems we fix

The Hono problems that bring people to us, and what you have once each one is fixed.

c.env.DB is undefined

Cloudflare binding missing at runtime

A D1 or KV binding declared in wrangler.toml for production but missing from the local preview environment, or renamed without a wrangler config update. Handlers crash on the first access.

Bindings consistent across environments

cors after auth, preflight 401

Middleware order breaking CORS

The auth middleware rejects an OPTIONS preflight before the cors middleware gets a chance to answer it, so browsers never make the real request and the app looks broken for cross-origin callers.

Order rearranged, preflight answered

Service Worker API used but modules required

Workers format mismatch

Code written for the old Service Worker format being deployed against a modules-based Worker, or vice versa. Fetch event handlers do not fire in the wrong format.

Format aligned with wrangler.toml

hc client: type not assignable

RPC types out of sync with server

Server route changes that the client has not picked up, or a build that did not rebuild types before the client imported them. Compile errors look like bugs, they are really stale types.

Types rebuilt as a dependency step

ReadableStream not supported in Node 16

Runtime mismatch breaks streaming

Code that relies on Web Streams running on an older Node version where they are not available, which usually means the deployment pipeline is pulling the wrong runtime image.

Runtime matched to the code

Response constructed with ReadableStream twice

Stream body consumed more than once

A handler or middleware that reads the response body and then passes it on, violating the single-consumer rule for Web Streams. The error fires at the edge and not during local tests.

Response bodies consumed once

zValidator: unknown keys dropped

Schema silently drops extra fields

A Zod schema configured with default stripping behaviour that drops fields the client actually sends, which looks correct until a feature depends on one of those fields being carried through.

Validators explicit about unknown keys

cf-connecting-ip missing

Client IP missing behind a custom proxy

A deployment where a front-door proxy strips or renames the Cloudflare connecting-IP header, breaking rate limiting or audit logs that trusted it.

Trusted proxy chain and header mapping

What we do

Hono help, from edge routing to RPC

Call us for one failing route, or let us design the whole Hono app across the runtimes it has to live on.

Edge deployments
Cloudflare Workers, Pages, Fastly Compute and Vercel Edge set up with real bindings, env separation and a deploy pipeline that works the same for every environment.
Multi-runtime design
Code structured so Node, Bun and Deno share handlers cleanly, with the runtime differences handled in thin adapters rather than leaking into business logic.
Typed RPC
hc clients wired so server route changes flow into type errors at build time, with build scripts that stop stale types from shipping.
Validation
Zod, Valibot or TypeBox schemas chosen deliberately, with validators configured to reject unknown fields rather than silently drop them.
Observability on the edge
Logs, traces and metrics shipped from Workers and other edge runtimes to the APM you already run, rather than being locked in the wrangler tail output.
Managed Tech
Hono and adapter versions tracked, Cloudflare and Bun release notes watched, and the app re-verified against new runtime versions before upstream rolls them out under you.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Hono alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Hono questions

Something else? Call+1 737 727 7327

Should we pick Hono or Fastify?

Hono when the application has to run on edge runtimes (Cloudflare Workers is the common driver) or when multi-runtime portability is a real requirement. Fastify when the service is a conventional Node.js API where you would rather have the richer plugin ecosystem and the compiled-schema performance story. Many teams run both in different places and pick per service.

Why does my Hono middleware behave differently locally versus on Workers?

Usually two causes: a runtime difference in Web Standards (streams, crypto, cookies) that masks the issue locally, and bindings that exist in wrangler.toml but are missing from the dev environment. Reproduce against wrangler dev with the production bindings mapped, and the surprise disappears.

How do we keep Hono RPC types stable under refactors?

Treat type generation as a real build step, not a side effect. Build the server, export its AppType, and have the client import types from the built artifact rather than from source. Run the client type check in CI so a server route change that broke the client is caught before merge.

Can we move an Express API to Hono?

Technically yes, and the gain is real if the target is an edge runtime. The Express middleware model does not translate one-for-one, so the move is more than a rename of app.use calls. We usually prefer to migrate route group by route group rather than in one sweep, especially for APIs with ambient middleware behaviour that is hard to see from code alone.

How do we handle streaming responses in Hono?

Return a Response wrapping a ReadableStream, or use the streaming helpers Hono ships. The important thing is that the body is consumed exactly once in the pipeline; any middleware that reads and re-emits the body must do so through a tee or a buffered rewrite. Local tests on Node do not catch all the places this goes wrong at the edge.

How much does Hono help cost?

We quote for free. Describe the runtime target and the symptom, whether that is a failing deploy, a cross-origin issue or an RPC type drift, and a price comes back before any code is touched.

Free estimate

Hono giving you trouble?

Tell us what you're running and what's going wrong. A person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.