What Is Next.js Middleware? The Invisible Layer AI Adds to Your App

Why AI Coders Need This

Here's how it happens: you're building a Next.js app with Cursor or Claude Code. Everything's working. You have a dashboard, a settings page, maybe a profile page. Then you say the magic words:

"Add auth protection so only logged-in users can see the dashboard."

AI doesn't add an if (!user) check to your dashboard page. Instead, it creates a brand-new file you've never seen before — middleware.ts — at the very root of your project. This file doesn't render anything. It doesn't have a UI. It sits there silently intercepting every single HTTP request before your pages even know someone's visiting.

If you don't understand what middleware is, this feels like AI went rogue. You asked for a simple auth check and got an invisible layer that controls your entire app's traffic. But this is actually the correct pattern. The reason AI reaches for middleware instead of page-level checks is that middleware handles auth in one place, for every route, without duplicating logic across dozens of files.

The problem? AI rarely explains what it just did. You're left with a file you didn't ask for, running code you don't understand, on a runtime you've never heard of. Let's fix that.

The Real Scenario

Simple enough request. You want three pages behind a login wall. Here's what AI generates — and it's probably not what you expected.

What AI Generated

Instead of modifying your three page components, AI creates this file at your project root:

// middleware.ts — at the root of your project
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Check if user has a session token
  const token = request.cookies.get('session-token')?.value;

  // If no token and trying to access protected routes, redirect to login
  if (!token) {
    const loginUrl = new URL('/login', request.url);
    // Save where they were trying to go so we can redirect back after login
    loginUrl.searchParams.set('callbackUrl', request.pathname);
    return NextResponse.redirect(loginUrl);
  }

  // Token exists — let the request through
  return NextResponse.next();
}

// Only run middleware on these routes
export const config = {
  matcher: ['/dashboard/:path*', '/settings/:path*', '/profile/:path*'],
};

That's it. No changes to your dashboard page. No changes to your settings page. This one file — sitting at the project root, never imported by anything — handles auth for all three routes automatically. Every request to those paths gets intercepted before the page even starts rendering.

Let's break down exactly what each part does.

Understanding Each Part

The Matcher Config

This is the most important part to understand, and the one AI gets wrong most often:

export const config = {
  matcher: ['/dashboard/:path*', '/settings/:path*', '/profile/:path*'],
};

The matcher tells Next.js: "Only run this middleware on these specific URL patterns." Without a matcher, middleware runs on every single request — including images, CSS files, fonts, favicons, and API calls. That's almost never what you want.

The :path* syntax means "this route and everything under it." So /dashboard/:path* matches /dashboard, /dashboard/analytics, /dashboard/users/123, and any other nested path.

NextResponse — The Three Actions

Inside middleware, you have three main things you can do with a request:

// 1. Let the request through (do nothing)
return NextResponse.next();

// 2. Redirect the user to a different URL (browser sees the redirect)
return NextResponse.redirect(new URL('/login', request.url));

// 3. Rewrite the URL (user sees one URL, server serves a different page)
return NextResponse.rewrite(new URL('/maintenance', request.url));

next() means "I'm done, proceed normally." redirect() sends the user to a different page (the browser URL changes). rewrite() secretly serves a different page without changing the URL — the user thinks they're on /dashboard but they're actually seeing your maintenance page.

Cookies and Headers

Middleware can read and set cookies and headers on both the request (incoming) and response (outgoing):

export function middleware(request: NextRequest) {
  // Read a cookie from the incoming request
  const token = request.cookies.get('session-token')?.value;
  const theme = request.cookies.get('theme')?.value;

  // Read a header from the incoming request
  const country = request.headers.get('x-vercel-ip-country');
  const userAgent = request.headers.get('user-agent');

  // Create a response and modify it
  const response = NextResponse.next();

  // Set a cookie on the outgoing response
  response.cookies.set('visited', 'true', { maxAge: 60 * 60 * 24 });

  // Set a header on the outgoing response
  response.headers.set('x-custom-header', 'middleware-was-here');

  return response;
}

This is how middleware handles things like A/B testing (set a cookie to assign users to a test group), geo-routing (read the country header and rewrite to a localized version), or analytics (add tracking headers to every response).

The Edge Runtime

Here's the part that causes the most confusion: middleware doesn't run on your normal Node.js server. It runs on the Edge Runtime — a stripped-down JavaScript environment designed to be fast and globally distributed.

Think of it this way: your regular server-side code runs in a data center somewhere. Edge functions run on CDN nodes spread across the world, closer to your actual users. This means middleware adds almost zero latency — it intercepts requests in a few milliseconds, not hundreds.

The tradeoff? The Edge Runtime is limited. You can't use many Node.js APIs. You can't access the file system. You can't use most database drivers. You can't import large npm packages that depend on native code. This is the #1 source of middleware bugs that AI creates — more on that in a moment.

Common Use Cases

Here's what middleware is actually good for — and what it's not:

What middleware is NOT for: database queries, sending emails, processing payments, rendering HTML, returning JSON responses, or any heavy computation. Those belong in API routes or server components.

What AI Gets Wrong About Next.js Middleware

Middleware is one of those features where AI generates code that looks right, passes TypeScript checks, and then breaks in production. Here are the five most common failures:

// Always exclude the login page from auth checks
if (request.nextUrl.pathname.startsWith('/login')) {
  return NextResponse.next();
}

Debugging Middleware with AI

Middleware bugs are tricky because the file runs invisibly — you don't see it in the browser, and errors often show up as mysterious redirects or blank pages rather than clear error messages. Here's how to debug effectively:

You can also add temporary logging to see what middleware is doing:

export function middleware(request: NextRequest) {
  // Temporary debug logging — check your terminal/Vercel logs
  console.log('Middleware hit:', request.nextUrl.pathname);
  console.log('Has token:', !!request.cookies.get('session-token'));
  console.log('Method:', request.method);

  // ... rest of your middleware logic
}

These logs show up in your terminal during development (next dev) and in your Vercel function logs in production. Remove them before deploying — middleware runs on every matched request, and excessive logging can hit your log limits fast.

This prompt saves you from putting the wrong logic in the wrong place. AI is good at explaining the boundary between middleware and other server-side patterns — it just doesn't always follow its own advice when generating code.

Testing Middleware Locally

Middleware behaves differently in development vs. production. In next dev, it runs in a simulated Edge Runtime. Some things that work locally might fail on Vercel because the real Edge Runtime is stricter. If your middleware works locally but breaks in production:

// Test with the edge runtime flag in next.config.js (Next.js 15)
/** @type {import('next').NextConfig} */
const nextConfig = {
  // This doesn't change middleware behavior, but helps catch issues early
  experimental: {
    // Middleware is always edge — this is just a reminder
  },
};

module.exports = nextConfig;

The real test: deploy to a preview branch on Vercel and test there. That's the actual Edge Runtime your middleware will run on in production.

When NOT to Use Middleware

Just because AI generates a middleware file doesn't mean you need one. Here's when to push back:

• Simple page-level auth: If you're only protecting one page, a server-side check in that page's server component is simpler and more obvious than a middleware file.
• Database-dependent decisions: If the check requires a database query (like "is this user an admin?"), do it in a server component or API route where you have full Node.js access.
• Heavy computation: Anything that takes more than a few milliseconds doesn't belong in middleware. The whole point is speed.
• Returning data: Middleware can redirect and rewrite, but it's not designed to return JSON responses or render HTML. That's what API routes and pages are for.

A Complete Real-World Middleware

Here's a production-ready middleware that combines several common patterns. This is closer to what you'd actually ship:

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

// Routes that don't require authentication
const publicRoutes = ['/login', '/signup', '/forgot-password', '/'];

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const token = request.cookies.get('session-token')?.value;

  // 1. Auth check for protected routes
  if (!publicRoutes.some(route => pathname.startsWith(route)) && !token) {
    const loginUrl = new URL('/login', request.url);
    loginUrl.searchParams.set('callbackUrl', pathname);
    return NextResponse.redirect(loginUrl);
  }

  // 2. Redirect logged-in users away from login page
  if (pathname === '/login' && token) {
    return NextResponse.redirect(new URL('/dashboard', request.url));
  }

  // 3. Add security headers to all responses
  const response = NextResponse.next();
  response.headers.set('X-Frame-Options', 'DENY');
  response.headers.set('X-Content-Type-Options', 'nosniff');
  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');

  return response;
}

export const config = {
  matcher: [
    /*
     * Match all paths except:
     * - _next/static (static files)
     * - _next/image (image optimization)
     * - favicon.ico (browser icon)
     * - public folder assets
     */
    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
};

Notice the pattern: auth first, then redirects for logged-in users, then security headers on everything. Each concern is one short block. The matcher excludes static files so middleware doesn't waste cycles processing image requests.

Frequently Asked Questions