#Middleware
Intercept requests before a page renders.
Middleware runs before page rendering and can short-circuit requests with a
custom Response - useful for auth, geolocation, A/B testing, redirects, and
bot detection.
#File convention
Create middleware.ts at the project root (or in src/):
// middleware.ts
export function middleware(request: Request) {
// Return a Response to short-circuit (redirect / rewrite / custom response).
// Return undefined / null to continue to the page handler.
const url = new URL(request.url);
if (url.pathname.startsWith("/admin") && !isAuthed(request)) {
return Response.redirect(new URL("/login", request.url));
}
}The handler can be the default export instead. A file with neither is a build
error (KR7143), and a server running such a module answers 503 rather than
letting requests through.
| Return value | Behavior |
|---|---|
Response |
Short-circuits - the response is served instead of the page (any status, including 200) |
Response with an x-middleware-next: 1 header |
Continues to the page handler; the response's other headers are added to the final response |
Response with an x-middleware-rewrite: /other header |
Continues, serving the page at /other (the browser URL does not change) |
undefined / null |
Continues to the page handler |
A pass-through response can also change the request the page, API route or
action sees, with the headers Next.js uses for
NextResponse.next({ request: { headers } }): x-middleware-override-headers
lists the request headers to keep (comma separated, all others are removed) and
x-middleware-request-<name> carries the value of each. Layouts read them with
headers(). These headers never reach the client.
export function middleware(request: Request) {
const url = new URL(request.url);
return new Response(null, {
headers: {
"x-middleware-next": "1",
"x-middleware-override-headers": "cookie,x-site-url",
"x-middleware-request-cookie": request.headers.get("cookie") ?? "",
"x-middleware-request-x-site-url": url.pathname + url.search,
},
});
}async middleware is supported. A thrown error (or a rejected promise) fails
closed with 503 middleware failed and is logged with its message; in dev the
message is included in the response body.
To add headers to every response without short-circuiting, return a pass-through response:
export function middleware(request: Request) {
return new Response(null, {
headers: { "x-middleware-next": "1", "x-frame-options": "DENY" },
});
}Repeated Set-Cookie headers are preserved individually (use
headers.append("set-cookie", ...)).
#The request
request is a standard Web Request: request.url is the absolute URL the
client used (built from the Host header, so
new URL("/login", request.url) redirects on the right host),
request.headers.get("cookie") is case-insensitive, and
request.cookies.get(name) returns { name, value } like Next.js. Behind a
reverse proxy that rewrites Host, set
server.trustProxy so the original
X-Forwarded-Host / X-Forwarded-Proto are used.
#Scoping with matcher
By default middleware runs for every page request, API route
(/api/*) and server action, but skips static assets (requests whose path ends
in a file extension such as .css, .js, .png, .woff2). Export a
Next-compatible config.matcher to choose exactly which paths run it:
export const config = {
matcher: [
"/dashboard/:path*", // /dashboard and everything below it
"/account",
"/((?!_next|favicon.ico).*)", // regex group with a negative lookahead
],
};Supported syntax: literal paths, :name, :name*, :name+, :name?,
parenthesised regular expressions, and { source: "/path" } objects. When a
matcher is declared it applies to every path, including assets. has,
missing and locale conditions are not supported by the embedded runtime and
fail the middleware with an explanatory error.
#How it's wired
middleware.tsis compiled to.krate/middleware.jsduring the build.- By default it runs in the embedded QuickJS runtime, from a pool of VMs
(one request does not wait for another). Set
ssr.middlewareRuntime: "node"(or"bun"/"deno") to run it in the sidecar instead. The embedded runtime has the same Web APIs as API routes, and the build warns withKR7160when middleware uses one it lacks. A middleware that imports a Node built-in or a database driver cannot run there at all: the build then compiles it for the Node sidecar on its own, andkrate migrate nextjswritesssr.middlewareRuntime: "node"for such a middleware. If a middleware fails to load,krate startrefuses to start (the Node sidecar and the serverless handler answer 503) instead of serving without it. - In
krate dev, the module is reloaded whenever.krate/middleware.jschanges (and picked up if you add it while the server runs). - Combined with redirects & rewrites, middleware gives you request-level control over routing.
#Use cases
- Auth - redirect unauthenticated users.
@krate/authdoes this fromauth.protectrules, see Authentication. - Bot detection - serve a custom response to known bots.
- A/B testing - rewrite requests to different variants.
- Header injection - set security headers per route.
Last updated: 2026-11-17
Contributors: Noinkin