What Is Middleware and How It Runs
Middleware in Next.js is defined in a single middleware.ts (or .js) file at the root of your project, or inside the src directory if you use one, and it runs on every matched request before that request reaches a route handler, page, or static asset. It executes on the Edge Runtime by default, a lightweight JavaScript environment based on web standard APIs rather than the full Node.js runtime, which lets it run geographically close to the user at the network edge with very low latency. The exported middleware function receives a NextRequest object and must return either NextResponse.next() to continue to the intended destination, or a modified response such as a redirect, rewrite, or an early response body.
Cricket analogy: Middleware is like the pitch inspector checking playing conditions before the umpires even walk out, a mandatory check that happens before the match proper begins.
The matcher Config
By default, middleware runs on every request, which is expensive and often unnecessary, so you export a config object with a matcher property to scope it to specific paths using path patterns similar to those used in route matching. The matcher accepts a single string, an array of strings, or objects with source, has, and missing conditions for more advanced matching, such as running middleware only on requests that carry a particular cookie or header. A common pattern excludes static assets and Next.js internals with a negative lookahead regex like '/((?!_next/static|_next/image|favicon.ico).*)', ensuring middleware only executes for actual page and API routes.
Cricket analogy: The matcher config is like a stadium's bag-check policy applying only to spectator gates, not to the players' entrance, targeting exactly the traffic that needs screening.
// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
export function middleware(request: NextRequest) {
const token = request.cookies.get('session')?.value;
if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
const loginUrl = new URL('/login', request.url);
loginUrl.searchParams.set('from', request.nextUrl.pathname);
return NextResponse.redirect(loginUrl);
}
return NextResponse.next();
}
export const config = {
matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};Common Use Cases: Auth, Redirects, Rewrites
The most common middleware use cases are authentication gating, where an unauthenticated user hitting a protected path is redirected to a login page with NextResponse.redirect(), and URL rewriting, where NextResponse.rewrite() serves different content for a URL without changing what's shown in the browser's address bar, useful for A/B testing or serving locale-specific content transparently. Middleware can also read and set cookies via request.cookies and response.cookies, and it can inspect headers such as geolocation data or the Accept-Language header to implement internationalization routing that redirects a user to /en or /fr based on their browser preferences before any page code runs.
Cricket analogy: NextResponse.redirect is like an umpire sending a batter back to the pavilion after a clear dismissal, visibly changing their destination, while rewrite is like a commentator quietly correcting a scorecard typo without announcing it to the crowd.
Middleware Limitations and Edge Runtime Constraints
Because middleware runs on the Edge Runtime by default, it cannot use most Node.js-specific APIs like fs for file system access, and any npm package it imports must be Edge-compatible, which rules out many database drivers that rely on raw TCP sockets rather than fetch-based HTTP connections. Middleware also has a bundle size limit (historically around 1MB to 4MB depending on the deployment platform) since the whole function is shipped to and executed at edge locations, so heavy logic or large dependencies should be avoided in favor of lightweight checks like cookie presence or JWT signature verification with a Web Crypto compatible library. As of Next.js 15.2, an experimental Node.js runtime option for middleware exists behind a flag, but Edge Runtime remains the stable default and the safest assumption when writing portable middleware code.
Cricket analogy: Edge Runtime's restrictions are like a rain-delay super-over having a strict, condensed rule set compared to a full five-day Test match, fewer tools available, but built for speed and quick decisions.
Middleware runs before the Next.js caching layer for a route decides what to serve, and before request processing in Server Components, so it's the earliest point at which you can inspect or modify an incoming request within your application code.
Because middleware executes on every matched request, expensive operations like uncached database calls or slow third-party API lookups inside it add latency to every single page load and API call under that matcher — even ones that don't strictly need the check. Keep middleware logic minimal, prefer signed cookies or JWTs you can verify locally over network calls, and scope the matcher as tightly as possible.
- middleware.ts at the project root runs on every matched request before it reaches a page, route handler, or asset.
- It executes on the Edge Runtime by default, a lightweight, web-standard-APIs-only environment.
- The config.matcher option scopes middleware to specific paths, commonly excluding _next/static and other internals.
- NextResponse.redirect() visibly changes the browser's URL; NextResponse.rewrite() serves different content silently.
- Middleware cannot use Node.js-only APIs like fs, and Edge-incompatible npm packages will fail to run.
- Bundle size limits apply to middleware since the function is deployed and executed at edge locations.
- Keep middleware logic lightweight (e.g. cookie checks, JWT verification) since it runs on every matched request and adds latency.
Practice what you learned
1. Where must middleware.ts be located in a Next.js project?
2. What runtime does Next.js middleware use by default?
3. What is the purpose of the config.matcher export?
4. What is the key difference between NextResponse.redirect() and NextResponse.rewrite()?
5. Why might a database driver fail to work inside Next.js middleware?
Was this page helpful?
You May Also Like
The Link Component and Navigation
Learn how Next.js's Link component powers fast, client-side navigation with automatic prefetching, and how to complement it with the useRouter and usePathname hooks.
Metadata and SEO in Next.js
Learn how to manage titles, descriptions, Open Graph tags, and structured metadata using the App Router's metadata object and generateMetadata, plus sitemap and robots conventions.
Loading and Error States
Learn how loading.js, error.js, and not-found.js use React Suspense and Error Boundaries to give every route automatic, granular loading and error UI.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics