How to access Workers bindings in Pages Functions with Hono?

[yudai-nkt]

UPDATE: With the stable v3 release, you can now use an adapter for this purpose. I'll keep Yusuke's answer marked as an answer for historical reasons but if you want to use Hono in Cloudflare Pages, please refer to the Adapter section of the release note.

---

I'm trying to use Hono with Cloudflare Pages Functions, but it seems that Hono's context cannot access to CF bindings.

Suppose I have the following Cloudflare Workers binding,

// functions/workers-binding.d.ts
type Env = {
  KV_FOR_REPRO: KVNamespace
}

and two routings for Functions, which are functions/api/raw.ts and functions/api/hono/[[route]].ts:

// functions/api/raw.ts
export const onRequestGet: PagesFunction<Env> = async ({ env }) => {
  await env.KV_FOR_REPRO.list();
  return new Response("Without Hono!");
};

// functions/api/hono/[[route]].ts
import { Hono } from "hono";

const api = new Hono<{ Bindings: Env }>();

api.get("/", async (c) => {
  await c.env.KV_FOR_REPRO.list();
  return c.text("With Hono!");
});

const app = new Hono();
app.route("/api/hono", api);

export const onRequestGet: PagesFunction = ({ request }) => app.fetch(request);

Then after starting a dev server by wrangler pages dev command, GET /api/raw returns "Without Hono!" but GET /api/hono returns "Internal Server Error" with the following log.

Trace: TypeError: Cannot read properties of undefined (reading 'list')
    at /private/Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/functions/api/hono/[[route]].ts:6:28
    at Hono.dispatch (/private/Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/node_modules/hono/dist/hono.js:136:15)
    at Hono.fetch (/private/Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/node_modules/hono/dist/hono.js:37:19)
    at onRequestGet (/private/Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/functions/api/hono/[[route]].ts:13:65)
    at next (/private/Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/node_modules/wrangler/templates/pages-template-worker.ts:152:28)
    at Object.fetch (/private/Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/node_modules/wrangler/templates/pages-template-worker.ts:171:17)
    at /Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/node_modules/@miniflare/core/src/standards/event.ts:350:19
    at /Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/node_modules/@miniflare/shared/src/event.ts:29:9
    at ServiceWorkerGlobalScope.<anonymous> (/Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/node_modules/@miniflare/shared/src/event.ts:77:9)
    at ServiceWorkerGlobalScope.[nodejs.internal.kHybridDispatch] (node:internal/event_target:731:20)
    at Hono.errorHandler (/private/Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/node_modules/hono/dist/hono.js:29:15)
    at Hono.handleError (/private/Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/node_modules/hono/dist/hono.js:122:19)
    at /private/Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/node_modules/hono/dist/hono.js:153:23
    at processTicksAndRejections (node:internal/process/task_queues:95:5)
    at next (/private/Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/node_modules/wrangler/templates/pages-template-worker.ts:152:22)
    at Object.fetch (/private/Users/ynkt/src/github.com/yudai-nkt/hono-with-pages-function-bindings/node_modules/wrangler/templates/pages-template-worker.ts:171:11)
GET /api/hono 500 Internal Server Error (52.87ms)

If I remove await c.env.KV_FOR_REPRO.list();, GET /api/hono returns "With Hono!" as expected. So there seems to be a problem in access to bindings rather than routing implementation itself.

I'm not sure if this is my mistake or a bug. Could anyone help me troubleshoot this? Reproduction repo is available at https://github.com/yudai-nkt/hono-with-pages-function-bindings

---

UPDATE: With the following module Worker and a dev server served by wrangler dev --local functions/worker.ts, GET /api/hono returns "With Hono!". So my problem is Pages-specific and therefore wrangler might be related to this (I'm not sure though).

// functions/worker.ts
import { Hono } from "hono";

const api = new Hono<{ Bindings: Env }>();

api.get("/", async (c) => {
  await c.env.KV_FOR_REPRO.list();
  return c.text("With Hono!");
});

const app = new Hono();
app.route("/api/hono", api);

export default app;

[yusukebe]

Hi @yudai-nkt !

If you want to use Hono in Pages Functions, you can use "advanced mode".

https://developers.cloudflare.com/pages/platform/functions/advanced-mode/
https://github.com/honojs/examples/tree/main/pages

With onRequestGet, it does not work well.

[yusukebe]

We can also write the utility function:

export const handle = (app: Hono) => {
  return (eventContext: EventContext<{}, string, {}>) => {
    const { request, env, waitUntil, passThroughOnException } = eventContext
    return app.fetch(request, env, { waitUntil, passThroughOnException })
  }
}

And use like this:

export const onRequest = handle(app)

The handle function is very short, but it's very useful for developers who want to use Hono in Cloudflare Pages. I think it's a good idea to make @hono/cloudflare-pages and export the function:

import { handle } from '@hono/cloudflare-pages'

[yudai-nkt]

Ah, I didn't notice app.fetch accepts the binding environment in the second argument although it has such type definition. Thanks so much!

P.S. for those wondering, let me introduce the motivation behind this question (I thought it was unclear why I wasn't using Pages Functions straightforward). I'm actually not a fan of filesystem-based routing tbh. It's useful and intuitive, but lacks type-safety. After some thought, I came up with the following idea:

• prepare a single Function file functions/api/[[route]].ts, which matches to any routes under /api regardless of the number of slashes.
• leave all the heavy lifting about routing to Hono, which can capture path parameters in a type-safe manner.

This is the ideal approach to me because I can develop type-safe API endpoints while benefitting from the functions/ mode mentioned above. Thanks to @yusukebe's help, I can now access to R2 and D1 in Function, and resume my app's server-side development again!

[yudai-nkt]

+1 for the @hono/cloudflare-pages (or possibly as one of package exports in Hono itself like hono/utils/cloudflare-pages?)! I also want to ask for others' opinion about the name. Deno uses serve for entry point while Lagon uses handler, and I don't know which sounds more natural.

[yusukebe]

Hi @yudai-nkt !

I've created the PR related to this matter. I think it's a good feature. Please check it!

#807

[yudai-nkt]

Thanks for the ping, I added a small comment there.

[yudai-nkt]

In v3.0.0-rc.8, you can use the handle adapter from hono/cloudflare-pages if you wish to use Hono in functions/. See https://github.com/honojs/starter/tree/main/templates/cloudflare-pages for scaffolding example.