Next.js Middleware and Edge Functions: A Practical Guide

What Is Next.js Middleware?

Next.js Middleware runs before a request is processed, at the edge (in Vercel's Edge Network, for example). It intercepts every request that matches your matcher config and can rewrite URLs, redirect users, modify headers, or return early responses. Middleware runs in the Edge Runtime — a lightweight runtime without Node.js APIs — so it is extremely fast with sub-millisecond cold starts.

Creating Your First Middleware

Create a middleware.ts file at the root of your project (same level as app/). Export a default middleware function that receives a NextRequest and returns a NextResponse. Use the config export with a matcher array to limit which routes the middleware runs on. Always be specific with your matchers — running middleware on every route including static assets is wasteful.

Authentication and Route Protection

Middleware is the ideal place for authentication checks. Read the session cookie or JWT token from the request, verify it, and redirect unauthenticated users to the login page. Libraries like NextAuth.js v5 and Clerk provide middleware helpers that handle this automatically. Because middleware runs at the edge before the page renders, unauthenticated users never receive the protected page HTML.

URL Rewrites and Redirects

Use NextResponse.rewrite() to serve content from a different URL without changing what the user sees in the browser — useful for A/B testing (rewrite to /variants/b without the URL changing) or multi-tenant apps (rewrite tenant-a.example.com to /tenants/tenant-a). Use NextResponse.redirect() for permanent or temporary URL redirects. Redirects in middleware are faster than page-level redirects because they happen before any rendering.

Geolocation and Internationalization

Middleware has access to the request's geolocation data (country, region, city) via request.geo on Vercel deployments. Use this to redirect users to their locale-specific version of the site, show region-specific content, or block access in certain jurisdictions. For i18n, read the Accept-Language header or geolocation and rewrite the URL to include the locale prefix.

Edge Runtime Limitations

The Edge Runtime does not support all Node.js APIs — no fs module, no native modules, no full crypto. Use the Web Crypto API instead of Node.js crypto. Middleware bundle size is limited (1MB on Vercel). Keep middleware lightweight — for complex logic, use middleware only to attach headers or tokens, then do the heavy processing in your server components or API routes.