Idea: deno-handler preset for library-mode embedding (sibling of deno-server)

[petarbasic]

Problem

The current deno-server preset calls Deno.serve() as a module-level side effect, so importing the built index.mjs immediately binds a port. There's no way to embed a Nitro build as a library in a parent Deno process.

Concrete use case: hosting many tenants in a single Deno process where a parent dispatcher routes by Host header. We work around the missing library mode today by having each Nitro build bind its own loopback port (127.0.0.1:400N) and the dispatcher does fetch("http://127.0.0.1:port/...") between them — adding TCP overhead, port-allocation logic, and Deno.env-race serialization to in-process communication that ought to be a function call.

Proposed solution

Add a sibling preset deno-handler (preserving deno-server as-is) that exports the handler instead of side-effecting a listen — mirroring how the Cloudflare preset family has both cloudflare-worker and cloudflare-module.

Consumer pattern:

// dispatcher.ts
import { fetch as siteA } from "./site-a/.output/server/index.mjs";
import { fetch as siteB } from "./site-b/.output/server/index.mjs";

const handlers = new Map([["site-a", siteA], ["site-b", siteB]]);

Deno.serve({ port: 3000 }, (req) => {
  const segment = (req.headers.get("host") ?? "").split(".")[0];
  return handlers.get(segment)?.(req)
    ?? new Response("unknown host", { status: 404 });
});

No per-build port binding, no localhost TCP. Same primitive Cloudflare Workers solves via isolate.fetch().

Implementation prototype

Draft PR: #4285 (against v2)

• 25-line runtime entry mirroring deno-server minus the Deno.serve() call
• Exports fetch (named) and default { fetch } matching cloudflare-module's convention
• Full conformance suite via test/presets/deno-handler.test.ts: 43/43 pass, identical to the deno-server v2 baseline
• End-to-end verified with two real Nitro builds + a multi-tenant dispatcher (no port binding at module import, all routing happens in-process)
• v3 / main port also ready locally — same shape, 49/49 conformance pass — happy to file as a follow-up PR once direction is agreed

Questions for maintainers

• Is library-mode embedding a direction you'd want supported in the Deno preset family at all? If so, is a sibling preset (this approach) preferred over e.g. a flag on deno-server that conditionally skips the listen?
• Naming: deno-handler follows the contract ("exports a handler"). Alternatives considered: deno-module (mirrors cloudflare-module), deno-library. Preference?
• Scope choices in the prototype that might warrant discussion:
  • Scheduled tasks deliberately omitted — library callers own scheduling. OK?
  • WebSocket upgrade requires the caller to pass info (Deno.ServeHandlerInfo) as the 2nd arg, throws clearly if missing. Acceptable?
  • No hooks.compiled — no deno.json emitted (embedding host owns it). OK?
• Anything else we should adjust before the PR moves out of draft?

[pi0]

I guess you can just use standard preset in your case it exports an standard web handler which should be compatible with deno out of the box.

[petarbasic]

Hey @pi0 — yeah, v3's standard ({ fetch: nitroApp.fetch }) is exactly the shape that fits here. Catch is v3 is still beta-only.

Would a v2 backport of standard be acceptable? Same name, same export shape, just adapted to v2's nitroApp.localFetch (which has the Web Fetch signature under a different name). ~20-line runtime; the patch adds src/presets/standard/ and registers it in _all.gen. WS stays out, matching v3.

Happy to retarget this PR or open a fresh one — whichever's cleaner.

Use case: multi-tenant Nitro hosting — one Deno process spawns a Web Worker per site, imports each site's fetch, proxies via postMessage. No per-site port binding, no localhost TCP between dispatcher and workers.

[pi0]

nitro v3 is designed based on web apis and way better for your usecase, nitro v2 was based on node apis. beta is mainly due to framework integrations.

[petarbasic]

Yeah, v3's the right shape for this. The catch is Nuxt 4.x still pins nitropack 2.x and that's not something we can move from our end, so v3's standard is kind of visible-but-unreachable. And there's a real production push behind it: collapsing ~20 per-site containers into one multi-tenant deno process. Works today on v2 with the patched preset;

Any chance you'd consider a minimal v2 backport of standard as an explicit stopgap until Nuxt picks up nitropack 3?

[pi0]

i would have love to but it is not practically a possible backport. all big efforts in Nitro v3 was to make standard preset first class.

I suggest to track progress of Nuxt v5 in this regard.

[fago]

Unfortunately, we'll need this working before Nuxt 5 lands.

What would be the best way to move forward? Would it make sense to add a deno-handler to v2 only? Or is that something a nuxt-module could add for Nuxt 4?

[pi0]

No it can't at least natively or reliably. Nitro v2 and H3 v1 ARE node.js based. web apis are only polyfilled.