Renew "Pages Framework guide" on Cloudflare Docs

[yusukebe]

Thanks to @rishavs, we have the documentation for Cloudflare Pages on the Cloudflare official site. That is one of "Pages Framework guides".

https://developers.cloudflare.com/pages/framework-guides/deploy-a-honojs-site/

And, in this PR cloudflare/cloudflare-docs#7410, @dario-piotrowicz improved it. That's great for us.

But, what Hono can do with Pages is not limited to what this document describes. We can make it as API for SPA in /functions or we can use JSX middleware for SSR. So, we have to renew the document.

Let's consider writing new documentation after v3 is released.

[yusukebe]

@dario-piotrowicz told me that the documentation to be put on Cloudflare Docs should be minimal. I think it's right.

cloudflare/cloudflare-docs#7410 (comment)

However, I think it's not a best, so either way, let's make it new.

[kpalmvik]

The instructions for getting started with Hono on Cloudflare Pages are currently significantly different if you compare:

• hono.dev: Cloudflare Pages
• Cloudflare: Deploy a Hono site

The most fundamental difference is that Cloudflare instructs you to configure and run Esbuild directly, while hono.dev uses Vite. Among other things this prevents Client components from working when following the Cloudflare instructions, since only the main worker will ever be transpiled.

On the other hand, following the instructions from hono.dev doesn't give you any obvious way to develop locally with live reload while also using Cloudflare bindings (such as KV, R2, D1 etc).

I might have missed something important, but it seems like the documentation should at a minimum be aligned. Ideally the instructions should also find a good tradeoff between the different configuration options.

[yusukebe]

Hi @kpalmvik

Yes. We should take an action.

On the other hand, following the instructions from hono.dev doesn't give you any obvious way to develop locally with live reload while also using Cloudflare bindings (such as KV, R2, D1 etc).

I think this is wrong. We can develop the Pages application using Hono and Bindings with live reloading. Have you ever tried it? https://hono.dev/getting-started/cloudflare-pages#bindings

[kpalmvik]

We can develop the Pages application using Hono and Bindings with live reloading. Have you ever tried it?

You are most likely correct, but for some reason I didn’t get it to work the first time. Will try again and get back soon.

[kpalmvik]

I can confirm that by following all the steps in Hono: Cloudflare Pages, including the Binding section, I seem to have a working local development environment! ✅ 🎉

Some feedback on the current instructions:

1. The step touch wrangler.toml seem to be redundant as npm create hono@latest my-app already created the file.

2. The step Edit vite.config.ts is redundant, since the file already has the exact same lines with a slightly different formatting/ordering.

3. When running npm run dev for the first time I got a (perhaps unrelated) Vite error: (!) Could not auto-determine entry point from rollupOptions or html files and there are no explicit optimizeDeps.include patterns. Skipping dependency pre-bundling.

4. The Client side instructions leaves out things such as how to implement a basic client component. There is no reference to Client Components, but that page doesn't cover all the parts either as far as I can understand.

   For example:

   • using a TSX file as the entrypoint (/src/client.tsx) does not seem to work even after changing input in vite.config.ts. To me it remains a bit unclear how it should be possible to do render(<App />, root) instead of render(App(), root)
   • The client component sources needs a "lib": ["dom"] entry in the tsconfig.json to allow document.getElementById("root");

[NicoPlyley]

Hi @yusukebe,

I faced a few issues with updating the documentation for Cloudflare. The command to create a Hono application is:

$ npm create cloudflare@latest my-hono-app -- --framework=hono

However, this will create an application with the cloudflare-workers template. Now, I can write documentation to show how to update it to the pages template, but as you mentioned:

the documentation to be put on Cloudflare Docs should be minimal.

It appears we are unable to create multiple options on c3, but if we allowed create-hono to accept an argument, that would update the template list to be just cloudflare-workers and cloudflare-pages. I think that would fix this, and I can update c3 accordingly.

I understand that this creates a bigger abstraction on top of the create-hono package, but I wanted to at least give the option. Let me know your thoughts, and I will proceed with changes accordingly.

[yusukebe]

Hi @NicoPlyley

Yes. I know about that issue, and I have some ideas.

It appears we are unable to create multiple options on c3, but if we allowed create-hono to accept an argument, that would update the template list to be just cloudflare-workers and cloudflare-pages. I think that would fix this, and I can update c3 accordingly.

Currently, create-hono already accepts --template options:

https://github.com/honojs/create-hono?tab=readme-ov-file#--template

So you can specify the template for create-hono command. But I think we can't pass the args to C3 and it's impossible to use cloudflare-pages template without modifying C3.

In Cloudflare internal, we are disuccusing about it but this not will resolved immediately.

---

For Hono, it's a little special because Hono can create a Web API for Workers or create web pages for Pages. So, my selfish suggestion is to introduce both Workers and Pages patterns. It's an exceptional case, but it will be best.

For example, the first section is for Workers and uses the C3 command. The second section is for Pages using create-hono directly. I think if we write them shortly, it will be a great document for the new users. What do you think about it?

[NicoPlyley]

@yusukebe, I want to explain what I was mentioning because I think it would fix the issue. However, we would be working around c3 rather than c3 working with Hono. And it would require two small modifications to c3.

If we had an option for a template (or another argument) like --template=cloudflare (this would not be a visible template, only accessible from the cli) it would then make the only option a user can select from the template list to be cloudflare-workers or cloudflare-pages. create-cloudflare Would have to be updated for the template command and to update the .ts or .tsx file to the same additions they already make.

I do understand if this is too much complexity. Or just does not make sense for a single use case. For now I will finish the docs for using create-hono instead since any updates would be minor.

[yusukebe]

@NicoPlyley

I see! C3 can't be changed immediately, so as you are doing, please use create-hono. Thanks!