Open yusukebe opened 1 year ago
@dario-piotrowicz told me that the documentation to be put on Cloudflare Docs should be minimal. I think it's right.
https://github.com/cloudflare/cloudflare-docs/pull/7410#issuecomment-1404947082
However, I think it's not a best, so either way, let's make it new.
The instructions for getting started with Hono on Cloudflare Pages are currently significantly different if you compare:
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.
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
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.
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:
The step touch wrangler.toml
seem to be redundant as npm create hono@latest my-app
already created the file.
The step Edit vite.config.ts is redundant, since the file already has the exact same lines with a slightly different formatting/ordering.
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.
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:
/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)
"lib": ["dom"]
entry in the tsconfig.json
to allow document.getElementById("root");
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.
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 allowedcreate-hono
to accept an argument, that would update the template list to be justcloudflare-workers
andcloudflare-pages
. I think that would fix this, and I can updatec3
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?
@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.
@NicoPlyley
I see! C3 can't be changed immediately, so as you are doing, please use create-hono.
Thanks!
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 https://github.com/cloudflare/cloudflare-docs/pull/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.