How does the config file work? What's the difference between using waku.config.ts and/or vite.config.ts?

[jkhaui]

Hey,

I really like the path Waku is pursuing as a lightweight React framework compatible with Vite, RSC, runtime/deployment agnostic, etc.

I have a question regarding the intended project setup. From my browsing of issues & discussions in this repo, my understanding is the goal is to shield end-users from having to setup a config file. However, for "power users", you can add a vite config file.

Just then I tried adding middleware to my starter project and noticed there's also the option to add a waku.config.ts file. Naturally this is where I'm confused and wondering, how does this work with a Vite config? Am I meant to use both together, or are they incompatible?

Thanks for clarifying!

[dai-shi]

Hey, thanks for trying out and asking.

The general goal is to have a good default and avoid "normal" users to require config files.
But, as it turns out, config files are required for "not-so-advanced" users for now.

We have two files waku.config.ts and vite.config.ts. Currently they are for different purposes, waku specific or not.
But, we will consider having a single config file to support both.

Until then, you should use both of config files up on your requirement.

[dai-shi]

If it looks like it's the best practice for the future, I think we should change the current CFW deploy script to CFP one. I didn't know which was the right choice and CFW seemed low-level, so that was it.

[jkhaui]

Yeah, it can be quite confusing. But at least Hono does most of the heavy lifting for us!

I guess I will start working on this following the pattern used by the other adapters: https://github.com/dai-shi/waku/tree/main/packages/waku/src/lib/builder. I'll call it cloudflare-pages to differentiate from the current cloudflare workers files

This is probably a good time to mention that I think adapters and having a modular adapter system is essential for Waku to gain traction and be well-recognised as an alternative React meta-framework to Next, Remix, Redwood, etc.

We could start thinking about how this can be architected such that the current lib builder files are extracted into separate packages e.g. npm i @waku/vercel. This could help make the core Waku package lighter to install in a dev environment, what do you think?

[dai-shi]

I think adapters and having a modular adapter system is essential

Yes, that's exactly what I thought, mainly because we can't maintain all adapters in this repo.
That should be definitely addressed before v1.

[jkhaui]

Btw, I had challenges getting my dev environment running on a Windows machine. But looks like I finally got it working by adding the cross-env package and creating a custom node script to properly handle loading of the NAME environment variable

Should I open a PR for this? I don't have a Mac/Linux so can't verify if it's broken anything on these OS

[dai-shi]

@himself65 should be using Windows. How does it work?

I'm against to adding cross-env. I think pnpm has a capability for posix compatibility?

[jkhaui]

Hey I'm revisiting this to try and get cloudflare pages integration working

I could definitely do with some pointers on how to get started as it's quite intimidating to learn the build process.

My understanding so far:

1. I should use Hono's Vite CF Pages plugin
2. I should find some way to add the plugin to Waku's internal build process, most likely somewhere in this file

Does this seem correct so far? Any other suggestions you might have? Cheers!

[dai-shi]

I should use Hono's Vite CF Pages plugin

I'm not sure. What does it do?

add the plugin to Waku's internal build process

That might be very tricky (and not stable) unless other plugins have done it.

[jkhaui]

I'm not sure. What does it do?

That might be very tricky (and not stable) unless other plugins have done it.

Thanks for getting back 🙏

Cloudflare Pages is the recommended way to host web apps on CF now, seems like worker sites are deprecated. CF pages gives a much better platform to build off with features like auto-deployments from git, accessing CF edge middleware, etc.

Seeing as Waku uses Hono internally I figured hono's CF pages plugin is what I should try to use.

Surprisingly I've actually made progress, I got a dev workflow going where I can inspect each step of the build process

I'll try figure out as much of this myself before asking for help. So far I've created with-cloudflare-pages as a new deployment type. Not sure if my understanding of the build process is correct, but here's how I'm approaching initial implementation:

1. Let waku handle most of the initial build steps (e.g. bundling the client, ssr, & rsc assets)
2. Add a new function like emitCloudflarePagesOutput where I'll call viteBuild and pass in the hono cf pages plugin with the entry file from dist specified

And I'm still trying to work out how serve-cloudflare-pages should fit into this. I also don't know if I'm approaching this completely wrong, I might just be duplicating the build process

[dai-shi]

Sounds good. I feel it will be a good experiment. As long as we agree that we may build things from scratch when we introduce a build plugin system, it should be fine.

I might just be duplicating the build process

If there is too much copy-paste code, there might be room for improvement.

[jkhaui]

Update: I was definitely approaching it incorrectly. Turns out CF Pages has something called "advanced mode" which we need to use. Advanced mode disables CF Pages file-based router which would conflict with waku's router

There's also no need to use the Hono CF plugin. Changes would be minimal and the build output will be very similar to the build created by -- --with-cloudflare.

If I can get it working with minimal changes, are you happy for me to open a PR adding -- --with-cloudflare-pages option? I don't mind if Waku's adapter system ends up being rebuilt

[dai-shi]

If I can get it working with minimal changes, are you happy for me to open a PR adding -- --with-cloudflare-pages option?

Yeah, I would like to delay the decision, but I feel like replacing the current one for CF workers with yours for CF pages.

[jkhaui]

Alright! I managed to get a minimal version working:

I set up my own pipeline and connected CF Pages to my clone of the Waku monorepo, building the examples/10_fs-router.

Even better is that in the end, almost no changes are needed; it's much simpler to just adapt the current -- --with-cloudflare setup to use CF Pages (advanced mode) instead of workers.

@dai-shi one last thing you can please help me understand: Cloudflare Pages require us to define all the paths for static clientside-only assets. This is so requests for these assets do not go through the server-side edge function (the errors in the console in the screenshot are because we have not yet defined the path/s where these static assets are).

Am I correct in saying that all client-only static assets reside under dist/public/assets?

[dai-shi]

I don't think it's a good idea to change the path. Can you somehow manage it on the deployment end?

[jkhaui]

I don't think it's a good idea to change the path. Can you somehow manage it on the deployment end?

Yeah I agree. It's proving more difficult than expected to find the solution, I need to understand Vite's build pipeline better. I'll update as I make progress

[jkhaui]

Ok looks like we've overcome this final blocker 🚀

The trick was to create a waku.config.ts file in the application code with the basePath: '/public/. I assume this probably needs to be set conditionally if we're in a CF Pages prod environment - or more likely it's a sign we need to make a more robust adapter system to handle it.

This is also a good example of how the ideal setup would be to have a single waku.config.ts which also exposes a top-level Vite config object. I got confused initially because I created vite.config.ts and set base, but it didn't do anything.

Anyway, very pleased because everything in this PoC is 100% working now! No more console errors. And when I click through the links I can confirm from the behaviour & what's logged in the network console is correct.

If I can find time today, you're happy for me to open a PR with the changes? And in this PR I should re-configure the -- --with-cloudflare arg to deploy to CF Pages instead of creating a new -- --with-cloudflare-pages flag? Happy to contribute to documentation too

[dai-shi]

you're happy for me to open a PR with the changes?

Yes.

Happy to contribute to documentation too

Yes please.

The trick was to create a waku.config.ts file in the application code with the basePath: '/public/.

It's a bit unfortunate for me. My hope was basePath should be freely configurable by users.
That said, I think changing basePath isn't properly supported yet anyway.
It feels a "hack" for cloudflare pages, but that's fine for now. We have full of hacks and cloudflare support is marked "experimental".
There must be a canonical solution, which we can find in the future.

This is also a good example of how the ideal setup would be to have a single waku.config.ts which also exposes a top-level Vite config object.

Yes, we have an idea to do it (there are some options). It's just that we have so many things piled up.
Definitely, it should be improved before v1.

[jkhaui]

Great. Busy with some other things now but will get onto it later

Yes, we have an idea to do it (there are some options). It's just that we have so many things piled up.

Definitely, it should be improved before v1.

I know. I think it's already tremendous Waku has a functional core because I can now see how complex it is to make a framework with basic SSR and RSC support.

Honestly, I think there needs to be more support from the core react team and/or Vercel to develop a Vite-native RSC plugin with deep integration of Vite's features like ESM bundling and virtual modules.

I like Next.js, but its batteries-included nature is not suitable for projects that just want a light framework with RSCs. And any Next.js alternative must be built on Vite because so much of the modern JS ecosystem is now dependent on Vite plugins.

This is where Waku fits in perfectly. It's just a shame it doesn't yet seem to be getting as much support as it should.

Anyway, sorry for going off-topic 😅 just wanted to share my opinion that if react's longevity is tied to the success of RSCs, then it's also in react's interest to provide other frameworks with first-class Vite RSC integration. A rising tide lifts all boats.

Let me know if I can help with any tasks needed for Waku!