Custom server entry

[rmarscher]

I don't love the unstable_honoEnhancer API. What if we supported an optional src/server.ts file? I think we could also refactor some of the code in cli.ts into a 'waku/server/node' module. If the server.ts file is not present, it could use this managed default:

import { unstable_createApp as createApp } from 'waku/server/node';

const app = createApp((app) => {
    // ability to enhance app before default middleware
});
// ability to enhance app after default middleware
export default app;

A Cloudflare deploy could look like this:

import { unstable_createApp as createApp } from 'waku/server/cloudflare';

const app = createApp();
export default {
    fetch: app.fetch,
}

The 'waku/server/cloudflare' createApp function would incorporate the code from our current deploy plugin that uses Cloudflare APIs instead of node:fs. https://github.com/wakujs/waku/blob/v0.22.4/packages/waku/src/lib/plugins/vite-plugin-deploy-cloudflare.ts#L24-L75

Eventually, maybe we can get our dev server integrated with Vite's environment API so we can use Cloudflare's module runner. It would use the src/server.ts file as its entrypoint. https://github.com/cloudflare/workers-sdk/blob/wrangler%404.13.0/packages/vite-plugin-cloudflare/src/runner-worker/module-runner.ts#L90

[dai-shi]

I'm afraid if there might be a misunderstanding, which I should have noticed earlier. unstable_honoEnhancer is basically required only for cli: waku (dev|build|start).
For more control, we should use serverEngine directly. Maybe you are aware of it already.

btw, our internals don't even depend on Hono.

What if we supported an optional src/server.ts file?

I'm not a big fan of it.
Can you create src/server.ts and call serverEngine in it? (and do not use cli)

I think we could also refactor some of the code in cli.ts into a 'waku/server/node' module.

This sounds good. Maybe waku/unstable_node module.

A Cloudflare deploy could look like this:

My goal is to move deploy plugins out of this repo or at least a separate package. So, something like waku-deploy-cloudflare.

[rmarscher]

OK. This blog post got me thinking about it. I thought the React Router worker code looked clean. https://blog.cloudflare.com/introducing-the-cloudflare-vite-plugin/

const requestHandler = createRequestHandler(
  () => import("virtual:react-router/server-build"),
  import.meta.env.MODE
);

export default {
  async fetch(request, env, ctx) {
    return requestHandler(request, {
      cloudflare: { env, ctx },
    });
  },
} satisfies ExportedHandler<CloudflareEnvironment>;

For more control, we should use serverEngine directly. Maybe you are aware of it already.

Right. importHono and serverEngine are available from "waku/unstable_hono". I guess this request is more about moving code from cli.ts to unstable_node or unstable_hono so custom servers can reuse it. startServer, loadConfig, notFound, serveStatic would be useful utilities to reuse when setting up a custom server.

btw, our internals don't even depend on Hono.

Maybe serverEngine could return a function that takes a Request object and returns a Response object then? That would allow it to target any WinterTC compatible server. Waku could still have a Hono adapter to wrap the fetch handler with a Hono server as the default server.

With Cloudflare, workerd will run a file that exports a handler that takes a request object so Hono wouldn't even be a dependency for the deployed code. Vercel edge functions are similar. https://github.com/wintercg/proposal-functions-api/tree/main/docs/implementations

There seems to be something limiting about Waku's context API, which is partly why I reach for Hono's context. Maybe the serverEngine options can include additional context data? That seems helpful for custom servers to just pass some resources down into the context rather than go through middleware.

It would also be nice to have access to the live Response object from anywhere. It is useful to know we know if headers have been sent as well as have the ability to manipulate headers on the response object immediately before the server component has finished rendering... with all the caveats about React suspense and concurrency. That's the other main reason I find a need for Hono's context. Maybe the Request and Response objects should go directly on the context and be accessible from server components and middleware.

something like waku-deploy-cloudflare

Yeah, that works. I think we can get started on that now. Would you want it in the wakujs org? It could also be possible to move it there later. (edit: or could be part of the waku monorepo as a separate package.)

[dai-shi]

To be honest, we are not ready to provide building block APIs. That's why I basically add unstable_ prefix to most ones, including unstable_honoEnhancer. Our focus for now is to provide a solid framework for normal use cases (!= custom server). Don't get it wrong: I'm very interested in providing unstable APIs and get more feedback.

I guess this request is more about moving code from cli.ts to unstable_node or unstable_hono

As I said, this makes more sense to me.

takes a Request object and returns a Response object then?

Our internal API is Middleware, which is smaller than Request and Response.
But, I agree that serveEngine has some logic that's not very Hono specific, so technically there can be a way to split.

That seems helpful for custom servers to just pass some resources down into the context rather than go through middleware.

I see. I hadn't thought about it and it's considerable, yeah.

It would also be nice to have access to the live Response object from anywhere.

The all caveats are the reason we don't have it, for the moment.
It's trivial to add res in our context.

waku/packages/waku/src/lib/middleware/context.ts

Lines 6 to 9 in e60b816

	type Context = {
	readonly req: HandlerReq;
	readonly data: Record<string, unknown>;
	};

Have you considered writing a custom middleware to expose res (of HandlerRes in Waku)?

Would you want it in the wakujs org? It could also be possible to move it there later. (edit: or could be part of the waku monorepo as a separate package.)

My plan is a separate repo in the wakujs org. Yes, you can start now. But, mark it like unstable or experimental as I think we should revisit the deploy adapter api.