How does Next.js middleware work, and what are its limitations compared to regular API routes?

Next.js Middleware

// middleware.ts (root of project)
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('session-token');

  // Protect dashboard routes
  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    if (!token) {
      return NextResponse.redirect(new URL('/login', request.url));
    }
  }

  // Role-based check
  if (request.nextUrl.pathname.startsWith('/admin')) {
    const role = request.headers.get('x-user-role');
    if (role !== 'admin') {
      return NextResponse.redirect(new URL('/unauthorized', request.url));
    }
  }

  // Add custom headers
  const response = NextResponse.next();
  response.headers.set('x-pathname', request.nextUrl.pathname);
  return response;
}

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

Where Middleware Runs

Middleware executes on the Edge Runtime, NOT Node.js:

Runs BEFORE the request reaches your page or API route

Runs on Vercel Edge, Cloudflare Workers, etc.

Cold start: ~50ms (vs ~250ms for serverless functions)

Limitations

FeatureMiddleware (Edge)API Routes (Node.js)

RuntimeEdge (V8 isolates)Node.js
Database access❌ No Prisma, no pg✅ Full access
File system❌ No fs✅ Available
Environment size1MB limitUnlimited
Execution time30s max (typically <5ms)10s default (configurable)
npm packagesEdge-compatible onlyAll packages
CryptoWeb Crypto APINode.js crypto
Cookies/HeadersRead + modifyRead + modify

Best Practice: Layered Auth

// Layer 1: Middleware — Fast checks (token exists? redirect?)
// middleware.ts
export function middleware(request: NextRequest) {
  const token = request.cookies.get('session-token');
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  return NextResponse.next();
}

// Layer 2: API Route — Deep validation (token valid? user exists? role check?)
// app/api/admin/users/route.ts
export async function GET(req: Request) {
  const session = await verifySession(req); // Full DB lookup
  if (session.role !== 'admin') {
    return Response.json({ error: 'Forbidden' }, { status: 403 });
  }
  // ... safe to proceed
}

// Layer 3: Component — UX (redirect if somehow reached)
// app/admin/page.tsx
import { redirect } from 'next/navigation';
export default async function AdminPage() {
  const session = await getSession();
  if (!session) redirect('/login');
  // ...
}

Rule: Middleware for routing decisions, API routes for data validation.