Demo

Middleware

Middleware runs before a request is completed, enabling auth, redirects, and rewrites.
Define middleware in a single middleware.ts file at your project root.
Middleware executes at the Edge for low-latency decisions close to users.
Use the matcher config to specify which routes trigger middleware.
Middleware can modify request headers, set cookies, redirect, or rewrite URLs.
Keep middleware fast — it runs on every matched request.

middleware.ts

1import { NextResponse } from 'next/server';
2import type { NextRequest } from 'next/server';
3
4export function middleware(request: NextRequest) {
5  // Check authentication
6  const token = request.cookies.get('session');
7
8  if (!token) {
9    return NextResponse.redirect(new URL('/login', request.url));
10  }
11
12  // Add custom header
13  const response = NextResponse.next();
14  response.headers.set('x-user-id', token.value);
15  return response;
16}
17
18export const config = { matcher: ['/dashboard/:path*', '/api/:path*'] };

Common Use Cases

Use Case	Implementation
Authentication	Check tokens, redirect to login
Redirects	Permanent or temporary URL changes
Rewrites	Serve different content at same URL
A/B Testing	Route users to different variants
Geolocation	Personalize based on user location

Demo

Navigate between sections and observe URL rewrites.
Trigger redirects and confirm query params are preserved.
Inspect response headers to see middleware additions.

Visual Summary

Middleware execution flow

Request

Matcher

Middleware

Route

Middleware runs at the Edge for low-latency decisions.

Key Takeaways

Topic	Guidance
Performance	Keep middleware lean; avoid heavy I/O
Security	Validate auth tokens before routing
Scope	Use matchers to limit which paths run middleware
Runtime	Edge runtime only — no Node.js-specific APIs

Pitfalls and Tips

Middleware cannot access Node.js-only APIs like fs or crypto.randomBytes.
Avoid fetching large payloads in middleware; use lightweight checks.
Always return a NextResponse — either next(), redirect(), or rewrite().
Use precise matchers to avoid running middleware on static assets.

Learn More

File Location

project/
├── middleware.ts   ← runs on matched routes
├── app/
│   └── ...

Basic Example

middleware.tstsx

Common Patterns

Auth Check

Redirect unauthenticated users to login

Geo Redirect

Route users to country-specific pages

A/B Testing

Rewrite to different page variants

Headers

Add security or custom headers

Matcher

The App Router Gallery

Auth Check

Geo Redirect

A/B Testing

Headers