Using route parameters

Most adapters natively support route parameters (also called parametric path or path parameters) such as /hello/:name. @universal-middleware/core provides the params helper to universally retrieve those.

We recommend to follow this next example when using route parameters:

// package: @universal-middleware-examples/tool
// file: src/handlers/params.handler.ts

import type { UniversalHandler } from "@universal-middleware/core";
import { params } from "@universal-middleware/core";

interface RouteParamOption {
  route?: string;
}

const handler = ((options?) => (request, _context, runtime) => {
  const myParams = params(request, runtime, options?.route);

  if (myParams === null || !myParams.name) {
    // Provide a useful error message to the user
    throw new Error(
      "A route parameter named `:name` is required. " +
        "You can set your server route as `/user/:name`, or use the `route` option of this middleware " +
        "to achieve the same purpose.",
    );
  }

  return new Response(`User name is: ${myParams.name}`);
}) satisfies (options?: RouteParamOption) => UniversalHandler;

export default handler;

NOTE

For servers supporting route parameters (app.get("/user/:name", myHandler())), the parameters are available under runtime.params.

For other adapters (app.get("/user/*", myHandler({ route: "/user/:name" }))), the 3rd argument of params helper must be present and not undefined. Then parameters are extracted with regexparam.

After bundling this middleware, one can then use this middleware as follows:

express.ts

import paramHandler from "@universal-middleware-examples/tool/params-handler-express";
import express from "express";

const app = express();

app.get("/user/:name", paramHandler());

export default app;

hono.ts

import { Hono } from "hono";
import paramHandler from "@universal-middleware-examples/tool/params-handler-hono";

const app = new Hono();

app.get("/user/:name", paramHandler());

export default app;

fastify.ts

import paramHandler from "@universal-middleware-examples/tool/params-handler-fastify";
import fastify from "fastify";

const app = fastify();

app.get("/user/:name", paramHandler());

export default app;

cloudflare-worker.ts

import paramsHandler from "@universal-middleware-examples/tool/params-handler";
import { createHandler } from "@universal-middleware/cloudflare";
import { pipe, type RuntimeAdapter } from "@universal-middleware/core";

const paramsHandlerInstance = paramsHandler({
  // Mandatory when targeting Cloudflare Worker
  route: "/user/:name",
});

// Cloudflare Workers have no native routing support.
// We recommend using Hono as it fully supports Cloudflare Worker.
const wrapped = pipe(
  (request: Request, ctx: Universal.Context, runtime: RuntimeAdapter) => {
    const url = new URL(request.url);
    // intercept `/user/*` routes with this handler
    if (url.pathname.startsWith("/user/")) {
      return paramsHandlerInstance(request, ctx, runtime);
    }
  },
  // Other handlers
);

export default createHandler(() => wrapped)();

cloudflare-pages.ts

// functions/user/[name].ts

import paramHandler from "@universal-middleware-examples/tool/params-handler-cloudflare-pages";

export const onRequest = paramHandler();

vercel-node.ts

// api/user/[name].ts

import paramHandler from "@universal-middleware-examples/tool/params-handler-vercel-node";

export default paramHandler();

vercel-edge.ts

// api/user/[name].ts

import paramHandler from "@universal-middleware-examples/tool/params-handler-vercel-edge";

export const GET = paramHandler();

h3.ts

import { createApp, createRouter } from "h3";
import paramHandler from "@universal-middleware-examples/tool/params-handler-h3";
import { universalOnBeforeResponse } from "@universal-middleware/h3";

const app = createApp({
  // /!\ This is required for universal-middleware to operate properly
  onBeforeResponse: universalOnBeforeResponse,
});

const router = createRouter();

router.get("/user/:name", paramHandler());

app.use(router);

export default app;

elysia.ts

import paramHandler from "@universal-middleware-examples/tool/params-handler-elysia";
import Elysia from "elysia";

const app = new Elysia().get("/user/:name", paramHandler());

export default app;

hattip.ts

import { createRouter } from "@hattip/router";
import paramHandler from "@universal-middleware-examples/tool/params-handler-hattip";

const app = createRouter();

app.get("/user/:name", paramHandler());

const hattipHandler = app.buildHandler();

export default hattipHandler;