rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

Mount a fetch handler#

Many libraries expose a Web-standard (request) => Response handler. There is no dedicated module for it: fromFetch from @rhythmjs/router/fetch wraps the handler as something mount accepts, and pathIs from @rhythmjs/router/path is the condition that limits it to the paths you give. Every other request carries on through the app untouched.

Shell
bun add @rhythmjs/rhythm @rhythmjs/router
TypeScript
import { Rhythm, mount } from "@rhythmjs/rhythm";
import { fromFetch } from "@rhythmjs/router/fetch";
import { pathIs } from "@rhythmjs/router/path";

const app = new Rhythm()
  .use(mount(fromFetch((request) => auth.handler(request)), pathIs("/api/auth/**")))
  .use(mount(api));

fromFetch copies the returned Response onto ctx.response: its status, status text, headers and body stream. Every Set-Cookie header is kept. Other headers replace same-named headers set earlier in the chain (CORS, for example) and leave the rest alone.

Paths follow the router's patterns#

pathIs(pattern) uses the same rou3 conventions as RhythmRouter: static segments, :name parameters, * and **. The HTTP method is not part of the match.

  • "/api/auth/**" matches /api/auth and everything beneath it at any depth, but not /api/authx. This is the usual choice for a library that owns a whole prefix.
  • "/hooks/:id/**" matches a named segment followed by anything.
  • "/**" mounts the whole app.

A pattern that does not start with / throws a TypeError when you call pathIs. Prefer ** over a trailing * for a catch-all: in the current rou3 a trailing * also matches deeper paths, so "/api/auth/*" does reach /api/auth/sign-up/email.

It is a mount, so the chain continues#

mount(plugin, condition) runs the plugin when the condition is true and then always calls next(). That means the response is written by the handler, and whatever follows in the app still runs: a later mount(api) finds no matching route under /api/auth/** and leaves the response alone, and middleware that acts after next(), such as compress() or secureHeaders(), sees the handler's response like any other.

An error thrown by the handler is wrapped (mounted module "fetch" failed) with the original as its cause; errorToResponse looks through the cause chain for a declared status.

Order matters#

Middleware registered before the mount runs for the mounted path too; put cross-cutting middleware such as cors() first, so a preflight is answered before the handler and the handler's responses carry the headers.

TypeScript
const app = new Rhythm<{}, RhythmHttpContext>()
  .use(cors({ origin: frontendOrigin, credentials: true }))
  .use(mount(fromFetch((request) => auth.handler(request)), pathIs("/api/auth/**")))
  .use(mount(api));

Things to check#

  • Router middleware such as rateLimit() or an authentication guard lives on a RhythmRouter and only runs for that router's routes, so it does not guard a mounted fetch handler. Protect those paths with the mounted library's own settings, or put app-level middleware before the mount.
  • The handler reads ctx.request; if an earlier middleware already consumed the body, clone it first.

The Better Auth recipe mounts its handler this way, with CORS in front. The functions are described in the API reference.