Middleware

better-router uses Hono middleware. A middleware is (c, next) => void | Promise<void>. Order on each request:

Request ALS context (getEnv() needs this)
Global files in src/middleware (sorted by file name)
Nested _middleware.ts from the matched route folder
Per-route middleware export or defineHandler(...) extras
Loader / action / HTTP handler

Global middleware

Files in src/middleware run on every request, including /api/*. Numeric prefixes control order.

src/middleware/01.logger.ts
src/middleware/02.cors.ts

src/middleware/01.logger.ts

import { defineMiddleware } from "better-router";

export default defineMiddleware(async (c, next) => {
  const started = Date.now();
  await next();
  console.log(c.req.method, c.req.path, c.res.status, `${Date.now() - started}ms`);
});

Any hono/* helper works. Install hono in the app and import it:

src/middleware/02.cors.ts

import { cors } from "hono/cors";

export default cors({
  origin: ["http://localhost:5173", "https://app.example.com"],
  credentials: true,
});

You usually do not need CORS for same-origin <Form> and <Link>. Add it when a separate frontend or mobile app calls /api.

Nested middleware

src/routes/admin/_middleware.ts applies to /admin/*. Use it to gate a whole tree:

src/routes/app/_middleware.ts

import { defineMiddleware } from "better-router";
import { HTTPException } from "hono/http-exception";
import { getCookie } from "hono/cookie";

export default defineMiddleware(async (c, next) => {
  if (!getCookie(c, "session")) throw new HTTPException(401);
  await next();
});

That throws 401 for unsigned-in users. For HTML dashboards, a layout loader that redirect("/login") is usually the better UX — see Errors.

Per-route middleware

Pass Hono middleware to defineHandler before the handler:

import { defineHandler } from "better-router";
import { basicAuth } from "hono/basic-auth";

export const GET = defineHandler(
  basicAuth({ username: "admin", password: "secret" }),
  (c) => ({ ok: true }),
);

Pages can export middleware from .server.tsx:

import { defineMiddleware } from "better-router";

export const middleware = defineMiddleware(async (c, next) => {
  c.set("requestId", crypto.randomUUID());
  await next();
});

Context variables

src/middleware/00.request-id.ts

import { defineMiddleware } from "better-router";

declare module "better-router" {
  interface AppVariables {
    requestId: string;
  }
}

export default defineMiddleware(async (c, next) => {
  c.set("requestId", crypto.randomUUID());
  await next();
});

Handlers then call c.get("requestId") with the right type.

Get started

Routing

Rendering

Deploy

Guides

Reference

Global middleware

Nested middleware

Per-route middleware

Context variables

​Global middleware

​Nested middleware

​Per-route middleware

​Context variables

Global middleware

Nested middleware

Per-route middleware

Context variables