Improved build adapters, new build config options

[rmarscher]

I've seen it mentioned that this project plans to revamp the build adapters before 1.0. Here are some ideas.

For the Cloudflare Pages adapter, I needed the public files to go into the root of the build folder and needed to create a _routes.json file to ignore them.

I'm now working on an AWS adapter - using SST Ion - and it needs the public folder separated out to upload to S3 and also needs to configure cloudfront routes to send the public assets to the s3 origin and send the rest of the routes to a Lambda function. You don't want it to bundle the public assets in with the Lambda function to keep the container size down.

It would be great if a few options could be moved into Config that are currently hard-coded within the build function. The DIST_SERVE_JS and DIST_PUBLIC values in packages/waku/src/lib/builder/constants.ts could be moved to Config. It would be great to add functionDir to output all of the server code into a sub-folder. The way the rscServePlugin gets added in the build could be customizeable from Config. So in Config, that would be:

  /**
   * The function output directory relative to the distDir.
   * This will be the folder to contain the built server files.
   * Defaults to ".".
   */
  functionDir?: string;
  /**
   * The public assets output directory relative to the distDir.
   * Defaults to "public". Use "." to output to the root of distDir.
   */
  publicDir?: string;
  /**
   * A built-in server adapter or path to a custom server entrypoint
   * Defaults to none. Options include 'deno', 'bun', 'vercel', 'netlify', 'cloudflare', 'aws-lambda'...
   */
  serve?: string;
  /**
   * If true, build for nodejs target. Otherwise, build for webworker.
   * Default is based on the value of serve
   */
  isNodeCompatible?: boolean; 

For Cloudflare Pages, it could use _worker.js as the functionDir folder and set . as the publicDir. So the build would output public to dist and the rest to dist/_worker.js. Or in my AWS build, I could do dist/public and dist/function.

The other common item needed for build adapters is a manifest of the public assets. Maybe the build function can return that. In the Cloudflare Pages case, it would then write a _routes.json file. In the AWS SST Ion case, it would create Cloudfront origin routes based on the manifest.

The various emit*Output functions could eventually be removed. Instead a build adapter could alter the default Config values, call the build function and then do additional operations on the build output.

It would probably be nice to have a hook to transform the Vite configs too. I'd like to enable sourceMaps, for example (although I saw there's a rollup issue, so maybe that isn't ready anyway).

[dai-shi]

Hi, thanks for opening up the discussion.

revamp the build adapters before 1.0

Yeah, but it's not a priority as we have so many issues/tasks piled, including revamping config system and so on.

a few options could be moved into Config that are currently hard-coded within the build function. The DIST_SERVE_JS and DIST_PUBLIC values

I don't think they are user configs. So, we may need a new mechanism other than the Config.

It would probably be nice to have a hook to transform the Vite configs too.

Hm, that makes me think that a build adapter can be a vite plugin.
I was a bit worried if we need to "invent" a new build adapter system.
If that works, we might be able to work on it from now, in parallel to other tasks.
It increases the vite dependency but it's reasonable.

[rmarscher]

Thanks! I will explore the possibility of a vite plugin to implement a build adapter.

[rmarscher]

Here is the AWS Lambda SST Ion adapter I mentioned in the description.

https://github.com/dai-shi/waku/compare/main...rmarscher:aws-lambda-sst?expand=1

I then use a custom SST Ion component I wrote. https://github.com/rmarscher/sst-ion-waku

It's using Lambda's streaming option and Hono's aws-lambda streamHandle. And it works! I'm loving how Waku uses Hono under the hood.

I could submit my branch as a PR... but maybe I should wait to see if I can reimplement it as a vite plugin.

[dai-shi]

tbh, I generally want to reduce hono and vite dependencies. nevertheless, build adapter system as vite plugin sounds nice. Let me know how it goes. There must be some design choices that I need to decide.

[jkhaui]

I definitely understand the desire to keep the Hono & Vite dependencies minimal However, given that deployment logic is mostly undifferentiated work, could we integrate Hono's existing adapter system and extend it with lifecycle hooks (e.g. waku:rsc-build, waku:ssr-build, etc.)?

IMO this would be the ideal solution. Even better if - as an end-user - I can just npm i @hono/node-server (or even use an adapter made by Hono's community, e.g. npm i @marplex/hono-azurefunc-adapter) and it just works with Waku.

The biggest challenge we're seeing with RSCs now is they're very difficult to get working in a way that's dev and bundler-friendly. And there's already very few devs capable of contributing to the existing challenges. So the rationale of this strategy is to free up dev resources to focus on issues specific to React 19, RSCs, etc.

These are just my thoughts atm. Maybe I'm missing something obvious why we can't do it this way :)

[dai-shi]

Actually, I did think about it when Waku was tightly integrated with Hono. AFAIR, there were technical difficulties.
That said, I think we can revisit it as I have a better understanding than before. It should probably be possible to still make the Hono dependency minimal (like adding a thin wrapper layer).

[jkhaui]

Nice!

On this topic, another potential use-case is exposing the cookie methods provided by Hono (https://hono.dev/docs/helpers/cookie).

I'm trying to build a full-featured app with all the major use-cases expected today. Auth is the key one but also the hardest to implement.

The reason it's particularly difficult with Waku atm is because there's no clean way to handle cookies - particularly how they interact with middleware and other server-side logic. Depending on your view, perhaps this is another opportunity to leverage Hono's built-in functionality as a "base" framework.

[dai-shi]

cookies with RSC is another hardest things to design. We can't always set cookies because of async nature with <Suspense>.

We do have unstable_getHeaders, so reading cookies might be trivial.

As for https://hono.dev/docs/helpers/cookie, we can expose Hono context in Waku's custom context. unstable_getCustomContext.

[dai-shi]

Related PRs:

• feat(build): introduce buildData in platformObject #860
• feat: deploy plugins #866, fix(deploy): move isNodeCompatible to deploy plugins #876
• experimental: expose hono context #852