Next.js Middleware

Run code at the edge before a request completes — redirect, rewrite, or modify responses

When to Use

• Protecting routes based on authentication or authorization state
• Redirecting users based on locale, geolocation, or A/B test bucket
• Rewriting URLs for feature flags or multi-tenant routing
• Injecting headers into requests or responses for security (CSP, CORS)
• Rate limiting or bot detection at the edge before hitting the server

Instructions

1. Create

   middleware.ts

   at the project root (or

   src/middleware.ts

   if using

   src/

   layout).
2. Export a default

   middleware

   function that accepts a

   NextRequest

   and returns a

   NextResponse

   or

   void

   .
3. Export a

   config

   object with a

   matcher

   array to scope middleware to specific paths — avoid running middleware on

   _next/static

   ,

   _next/image

   , and static assets.
4. Use

   NextResponse.redirect()

   for permanent redirects and

   NextResponse.rewrite()

   to proxy the request to a different URL without changing the browser URL.
5. Read cookies with

   request.cookies.get('name')

   and set them on the response with

   response.cookies.set()

   .
6. Use

   NextResponse.next()

   with modified headers to pass custom headers to Server Components via

   headers()

   .
7. Keep middleware fast — it runs on every matched request on the Edge Runtime. Avoid heavy computation, large imports, or network calls where latency matters.
8. Do not import Node.js-only modules — the Edge Runtime only supports a subset of Web APIs.

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('auth-token')?.value;
  const isProtected = request.nextUrl.pathname.startsWith('/dashboard');

  if (isProtected && !token) {
    const loginUrl = new URL('/login', request.url);
    loginUrl.searchParams.set('callbackUrl', request.nextUrl.pathname);
    return NextResponse.redirect(loginUrl);
  }

  // Pass a custom header to Server Components
  const response = NextResponse.next();
  response.headers.set('x-pathname', request.nextUrl.pathname);
  return response;
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)'],
};

Details

Next.js Middleware runs on the Vercel Edge Network (or a compatible edge runtime) before the request reaches the server. It uses the Edge Runtime — a lightweight V8 environment with Web APIs but without Node.js built-ins like

fs

,

path

, or

crypto

(use

globalThis.crypto

instead).

Matcher syntax: The

matcher

array supports path patterns, negative lookaheads, and regex. The example pattern is the recommended baseline: it excludes Next.js internals and static file extensions. Middleware that matches every request including static assets is a common performance mistake.

Reading server component headers: Middleware can inject headers into the request via

request.headers.set()

before calling

NextResponse.next({ request })

. These headers are accessible in Server Components via

import { headers } from 'next/headers'

. This pattern passes request-time context (user ID, locale, tenant) without touching cookies.

Edge vs Node.js runtime: Middleware always runs on the Edge Runtime. Route Handlers and Server Components can opt into the Edge Runtime with

export const runtime = 'edge'

, but this is optional and has the same Node.js API limitations.

Auth libraries: NextAuth.js / Auth.js provides a

auth()

middleware helper that integrates with the middleware pattern. Using it avoids manually parsing JWTs in middleware.

Source

https://nextjs.org/docs/app/building-your-application/routing/middleware

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.