Welcome to Next.js Middleware Mastery: The Ultimate Guide to Unlocking Edge Performance, Security, and Scalability

Let's dive in it

Fundamentals

1. What is Middleware in Next.js, where in the request–response cycle does it run?

In Next.js, Middleware is a function that runs before a request is completed or reachs the origin server - where your API route (server logic gets excute), allowing you to inspect, modify, and handle the request before it reaches a page or an API route.

Where does it runs in the request-response cycle?

The typical request-response cycle with Middleware looks like this:

1Step 1: Client makes a request.
2	User sends a request to your application (e.g., to /dashboard).
3Step 2: Middleware runs at the edge before your app code.
4	This is where you can inspect the request, check cookies, read headers, or decide whether to rewrite/redirect it.
5	(where your Middleware function runs.)
6Step 3: Middleware can either:
7	Pass the request along unchanged to your app, or
8	Redirect/Rewrite it to a different route, or
9	Return a custom response entirely.
10
11The final response is sent back to the user.

2. How does Middleware differ from API routes, getServerSideProps, and Server Components?

This is where people often get confused because all four (Middleware, API routes, getServerSideProps, Server Components) touch the request–response pipeline but at different stages and with different capabilities. (Middleware, API routes, getServerSideProps, and Server Components all serve different purposes in Next.js)

Middleware vs API Routes vs getServerSideProps vs Server Components

Middleware

1When it runs: 
2	Before a request reaches your app’s logic.
3
4Runtime: 
5	Edge Runtime (Web APIs, no Node.js APIs).
6
7Capabilities:
8	Inspect & modify request headers, cookies, URL.
9	Redirect or rewrite requests before they hit the route.
10	Run globally across multiple routes.
11
12Limitations:
13	No access to request body (e.g., JSON form POST).
14	No heavy computation (size limits + must be fast).
15
16Best for: Auth checks, A/B testing, geo-based routing, localization, IP blocking, lightweight security.

API Routes

1When it runs: 
2	When you hit an endpoint like /api/user.
3
4Runtime: 
5	Node.js server (or Edge if explicitly configured).
6
7Capabilities:
8	Full access to request + response body.
9	Can connect to databases, run heavy logic, perform CRUD operations.
10	Great for server-side business logic.
11
12Limitations:
13	Adds latency (round trip to server).
14	Scoped only to API endpoints (not global).
15
16Best for: REST/GraphQL APIs, handling POST/PUT/DELETE requests, data fetching from client.

getServerSideProps

1When it runs: 
2	At request time during page rendering.
3
4Runtime:
5	Node.js server.
6
7Capabilities:
8	Fetch data securely (DB calls, APIs).
9	Pass props directly to a React page.
10
11Limitations:
12	Runs on every page request, so it can be slower.
13	Only works in the Pages Router (deprecated in App Router).
14
15Best for: Preloading data for a page before rendering, especially when SEO matters.
16(In App Router, getServerSideProps is replaced by Server Components + fetch())

Server Components (App Router)

1When it runs:
2	At render time when React renders your tree.
3
4Runtime:
5	Node.js (or Edge if configured).
6
7Capabilities:
8	Fetch data directly in the component using async/await.
9	Run heavy logic without shipping JS to client.
10
11Composable — works inside your React tree.
12
13Limitations:
14	Runs per render, not globally.
15	Can’t intercept requests like Middleware does.
16
17Best for: Data-fetching and rendering UI in the App Router.

Comparison Table:

• Middleware = traffic cop at the highway entrance.
• API Routes = dedicated service windows.
• getServerSideProps = waiter fetching fresh ingredients for each dish.
• Server Components = chef cooking with those ingredients right in the kitchen.

3. What is the Edge Runtime in Next.js, how does it differ from the Node.js runtime, and why is Middleware sometimes faster than traditional SSR?

The edge runtime is a lightweigt, secure, and globally distributed Javascript execution environment, specially designed to run the code close to the user - at CDN edge location - rather then on centralized server.

In other words..

It is a lightweight execution environment that runs your code geographically close to the user - at the "edge" of the network - rather then the centralized server. which has ?signeficantly lower latency as comparied to any centralized server.

Example:

If a user in India visits a website such as example.com, and the main server of the site is located in US. Then all server based calculation is excuted in this main server (which is located in US) expect the Middleware. Middleware excutes at edge runtime, it means middleware for the user whoes geographical location is in India, runs the Middleware in the server of India (very close to user - edge of the network), and after middleware excution it pass the request to the main origin server (in US).

Key Characteristics

• Runs on V8 isolates (like Cloudflare Workers or Vercel Edge Functions)
• Cold starts are minimal — near-instant execution.
• Limited APIs: no access to Node.js core modules (e.g., fs, net, child_process). (It is designed for speed and low latency, not for heavy computation.)
• Designed for fast, stateless operations like redirects, header manipulation, and auth checks.
• In Next.js, Middleware and Edge Functions run in this runtime.

Edge Runtime vs Node.js Runtime

Why Is Middleware Sometimes Faster Than Traditional SSR?

Middleware is often faster than SSR because it runs on the edge - close to users, with near-zero cold starts. It executes before caching and routing, enabling instant redirects, auth checks, and request shaping without spinning up full rendering. SSR is heavier, centralized, and slower for these quick tasks.

Simplified explanation:

1. Execution Location:

   Middleware (Edge Runtime):

   Runs at globally distributed edge servers (Vercel’s Edge Network / PoPs). → Closer to the user = less round-trip time (RTT).

   SSR (Node.js Runtime):

   Runs in a centralized server or serverless function, often in a single region (e.g., AWS us-east-1). → Users far from that region face higher latency.

2. Startup Time (Cold Starts):

   Middleware:

   Runs in V8 isolates (lightweight, like WebAssembly). → Near-instant execution (cold starts <10ms).

   SSR:

   Runs in a full Node.js environment. → Cold starts can take 200–500ms, especially on serverless platforms.

3. Work Done Before Rendering:

   Middleware:

   Runs before caching and routing, so it can make instant decisions (redirects, rewrites, auth checks) without hitting your origin. → Example: If a request doesn’t have an auth token, Middleware can block it immediately instead of booting up SSR.

   SSR:

   Has to spin up rendering logic, fetch data, and generate HTML — even if the request could have been rejected earlier.

4. Caching Integration:

   Middleware:

   Works seamlessly with the CDN. It can shape requests and still serve cached content (super fast).

   SSR:

   Typically bypasses cache for dynamic responses, making every request heavier.

5. No HTML Rendering

   • Middleware doesn’t render HTML — it just intercepts and modifies requests.
   • SSR must fetch data, render HTML, and hydrate it before sending.
   • Middleware skips all that, making it ideal for lightweight tasks like redirects, auth checks, and header manipulation.

Simple Analogy Middleware = traffic cop at every street corner → stops or redirects cars instantly, close to where they are. SSR = central office downtown → every car must drive all the way there, even if it only needed a quick check.

In short:

Middleware is faster than traditional SSR because it’s lightweight, globally distributed, and runs before caching. SSR is more powerful (full Node.js + rendering), but slower due to centralized execution and heavier workloads.

File Structure & Configuration

4. How do you create a Middleware file in Next.js, including correct naming conventions and file structure for middleware.ts or middleware.js?

How to Create a Middleware File in Next.js?

File Name & Location

The middleware file must be named exactly:

middleware.ts (TypeScript)
middleware.js (JavaScript)

Place it in the root of your project (same level as pages/ or app/).

		my-app/
		├─ app/               # App Router
		├─ pages/             # Pages Router
		├─ public/
		├─ middleware.ts      # Middleware lives here
		└─ next.config.js

You cannot put it inside pages/ or app/ — Next.js won’t detect it there.

Basic Example

1// middleware.ts
2
3import { NextResponse } from 'next/server'
4import type { NextRequest } from 'next/server'
5export function middleware(request: NextRequest) {
6	// Example: Block access to /dashboard if not logged in
7	const isLoggedIn = request.cookies.get('token')?.value
8	if (!isLoggedIn && request.nextUrl.pathname.startsWith('/dashboard')) {
9		return NextResponse.redirect(new URL('/login', request.url))
10	}
11	// Allow request to continue
12	return NextResponse.next()
13}

Controlling Which Routes Middleware Runs On:

By default, Middleware runs on all routes.

You can scope it with the matcher config:

1// Only run on /dashboard and /profile
2export const config = {
3	matcher: ['/dashboard/:path*', '/profile/:path*'],
4}

What Does matcher Do?

1'/dashboard/:path*' matches:
2	/dashboard
3	/dashboard/settings
4	/dashboard/profile/edit
5[Same for /profile]

Naming Conventions Recap

In short:

• File = middleware.ts or middleware.js
• Location = project root
• Export a middleware() function
• Use NextResponse to rewrite, redirect, or continue requests
• Control scope with config.matcher

5. How do you configure Middleware for specific routes using the matcher option, and what is the execution order if multiple matchers exist?

How to Configure Middleware for Specific Routes Using matcher?

By default, Middleware runs on every request. To restrict it, you export a config object with a matcher property from your middleware.ts file.

Basic Syntax:

1// middleware.ts
2import { NextResponse } from 'next/server'
3import type { NextRequest } from 'next/server'
4
5export function middleware(request: NextRequest) {
6    return NextResponse.next()
7}
8
9export const config = {
10  matcher: ['/dashboard/:path*', '/profile/:path*'], // only these routes
11}

Matcher syntax

Next.js automatically excludes the following from Middleware:

• /_next/static/* (build assets)
• /_next/image/* (image optimizer)
• /favicon.ico

If you write your own regex matcher, you must account for these exclusions manually.

Execution Order with Multiple Matchers

In Next.js, you can only have one middleware.ts file, but you can define multiple matcher patterns inside its config. Matchers are evaluated independently. If a request path matches any of them, Middleware runs once for that request. The order of matchers in the array does not define priority or sequencing. Think of them as OR conditions. Inside the Middleware function, you can branch logic based on the request path (or other conditions).

Example 1

1export const config = {
2    matcher: [
3        '/dashboard/:path*',
4        '/profile/:path*',
5        '/admin/:path*',
6        '/((?!api|_next|favicon.ico).*)',
7    ],
8}

Explanation:

• /dashboard/:path* → matches /dashboard, /dashboard/settings, etc.
• /profile/:path* → matches /profile, /profile/edit, /profile/view/123, etc.
• /admin/:path* → matches /admin routes.
• /((?!api|_next|favicon.ico).*) → regex excludes internal Next.js routes and static files. Middleware still runs only once per request, no matter how many matchers match.

Example 2

1export const config = {
2    matcher: ["/((?!_next/static|favicon.ico).)", "/admin/:path"],
3}

Explanation:

• First matcher /((?!_next/static|favicon.ico).*) → applies to all routes except static files.
• Second matcher /admin/:path* → specifically matches admin routes.
• If a request matches either pattern, Middleware runs once, and you decide logic flow inside it.

In summary:

• Matchers are filters, not sequential rules.
• Middleware runs once if any matcher matches.
• Use conditional branching inside Middleware to handle different routes cleanly.

Core Features

6. What is the NextResponse object, and how can it be used to: redirect requests, rewrite URLs, and set custom headers?

What is the NextResponse object?

The NextResponse object is the powerhouse of control inside Next.js middleware. It’s what you use to respond to, redirect, rewrite, or modify an incoming request before it reaches your route handler.

It is a utility provided by Next.js that lets you:

• Continue the request (NextResponse.next())
• Redirect the user (NextResponse.redirect(url))
• Rewrite the request path (NextResponse.rewrite(url))
• Modify headers or cookies on the response

It’s part of the next/server module and is designed to work within the Edge Runtime.

Why do we need it?

Since Middleware runs before the request reaches your route handler or page, NextResponse acts as your “traffic controller.” It controls whether the request:

1. Proceeds normally,
2. Gets redirected,
3. Or gets handled differently (e.g., blocked, authenticated, rewritten).

How can it be used to: redirect requests, rewrite URLs, and set custom headers?

1. Redirect Requests

   Use NextResponse.redirect() to send users to a different URL. Perfect for auth guards, onboarding flows, or geo-based redirects.

   TYPESCRIPTCopy

   1import { NextResponse } from 'next/server'
   2import type { NextRequest } from 'next/server'
   3export function middleware(req: NextRequest) {
   4const isLoggedIn = req.cookies.get('token')?value
   5	if (!isLoggedIn && req.nextUrl.pathname.startsWith('/dashboard')) {
   6		return NextResponse.redirect(new URL('/login', req.url))
   7	}
   8	return NextResponse.next()
   9}

2. Rewrite URLs

   Use NextResponse.rewrite() to internally reroute a request without changing the URL in the browser. Great for A/B testing, feature flags, or serving content from a different path.

3. Set Custom Headers

   Use NextResponse.next() and then modify the response headers. Useful for security headers, caching, or passing metadata downstream.

   TYPESCRIPTCopy

   1export function middleware(req: NextRequest) {
   2	const response = NextResponse.next()
   3	response.headers.set('x-gs-powered-by', 'Next.js Middleware')
   4	response.headers.set('x-feature-flag', 'beta-dashboard')
   5	return response
   6}

You can also read headers from the request:

1const userAgent = req.headers.get('user-agent')

Combine All Three

You can mix and match these in a single middleware flow:

1export function middleware(req: NextRequest) {
2	if (req.nextUrl.pathname === '/old-route') {
3		return NextResponse.redirect(new URL('/new-route', req.url))
4	}
5	if (req.nextUrl.pathname === '/preview') {
6		return NextResponse.rewrite(new URL('/preview/index.html', req.url))
7	}
8	const response = NextResponse.next()
9	response.headers.set('x-gs-debug', 'active')
10	return response
11}

Common Methods

Why It Matters

• NextResponse gives you low-level control over how requests are handled.
• It’s optimized for the Edge Runtime, so it’s fast and lightweight.
• It’s the only way to manipulate requests/responses inside middleware — you can’t use res.writeHead() or res.end() like in Node.js.

7. What’s the difference between NextResponse.redirect() and NextResponse.rewrite()?

NextResponse.redirect() and NextResponse.rewrite() both change where the request resolves, but they work differently — redirect() sends the user to a new URL (browser address bar changes), while rewrite() serves different content at the same URL (browser address bar stays the same).

NextResponse.redirect()

• What it does: Redirects the user to a different URL.
• Effect: The browser’s URL changes (client sees the new URL).
• Use case: Redirecting unauthenticated users to /login, or redirecting old routes to new ones.

Example:

1import { NextResponse } from "next/server";
2export function middleware(req) {
3	const isLoggedIn = false;
4	if (!isLoggedIn) {
5		return NextResponse.redirect(new URL("/login", req.url));
6	}
7	return NextResponse.next();
8}

If a user visits /dashboard, they get redirected to /login, and the browser shows /login.

NextResponse.rewrite()

• What it does: Internally serves a different page while keeping the original URL in the browser.
• Effect: The browser’s URL does not change.
• Use case: Serving different content for the same route, A/B testing, localization, or proxying routes.

Example:

1import { NextResponse } from "next/server";
2export function middleware(req) {
3	const url = req.nextUrl;
4	if (url.pathname === "/about") {
5		return NextResponse.rewrite(new URL("/info", req.url));
6	}
7	return NextResponse.next();
8}

If a user visits /about, they see the content from /info, but the browser still shows /about.

Comparision Table

Key Difference

• redirect() → Changes the user’s URL (client-side redirect).
• rewrite() → Keeps the same URL but serves different content (server-side rewrite).

8. How do you read and set cookies inside Middleware, and how can you modify request or response headers for analytics, caching, or security (including adding CSP, CORS, HSTS, etc.)?

1. Reading & Setting Cookies in Middleware

In Next.js Middleware, you use the cookies API available on the NextRequest and NextResponse objects.

Read Cookies

1import { NextResponse } from "next/server";
2import type { NextRequest } from "next/server";
3export function middleware(req: NextRequest) {
4	// Reading cookies from the request
5	const token = req.cookies.get("token")?.value;
6	if (!token) {
7		// If no token, redirect to login
8		return NextResponse.redirect(new URL("/login", req.url));
9	}
10
11	return NextResponse.next();
12}

Set Cookies

1import { NextResponse } from "next/server";
2import type { NextRequest } from "next/server";
3export function middleware(req: NextRequest) {
4	const res = NextResponse.next();
5	// Set a cookie
6	res.cookies.set("user", "GS", {
7		httpOnly: true,
8		secure: true,
9		path: "/",
10		sameSite: "strict",
11	});
12	return res;
13}

You can also delete cookies: res.cookies.delete("token");

Cookies are great for auth tokens, user preferences, A/B testing buckets, and session hints — but remember, you can’t access the request body in middleware, so cookies are your best bet for lightweight state.

2. Modifying Request & Response Headers

In Next.js, cookies are primarily accessed through the request headers, but you can also read and write cookies in the response—especially in middleware, route handlers, and server actions.

You can add, remove, or update headers on the request or response for analytics, caching, or security.

Adding Custom Headers (Analytics / Debugging)

1export function middleware(req: NextRequest) {
2	const res = NextResponse.next();
3	// Example: custom analytics header
4	response.headers.set('X-Request-ID', crypto.randomUUID());
5	response.headers.set('X-Geo-Region', request.geo?.region || 'unknown');
6return res;
7}

Setting Security Headers (CSP, HSTS, CORS, etc.)

1export function middleware(req: NextRequest) {
2	const res = NextResponse.next();
3	// Content Security Policy
4	res.headers.set(
5		"Content-Security-Policy",
6		"default-src 'self'; script-src 'self' https://trustedscripts.example.com"
7	);
8	// Strict Transport Security (HSTS)
9	res.headers.set("Strict-Transport-Security", "max-age=63072000; includeSubDomains; preload");
10	// Cross-Origin Resource Sharing (CORS)
11	res.headers.set("Access-Control-Allow-Origin", "*");
12	res.headers.set("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
13	res.headers.set("Access-Control-Allow-Headers", "Content-Type, Authorization");
14	// Prevent clickjacking
15	res.headers.set("X-Frame-Options", "DENY");
16	// Prevent MIME-sniffing
17	res.headers.set("X-Content-Type-Options", "nosniff");
18	return res;
19}

Common Security Headers in Middleware

Example: Adding All Security Headers in Middleware

1import { NextResponse } from "next/server";
2import type { NextRequest } from "next/server";
3export function middleware(req: NextRequest) {
4	const res = NextResponse.next();
5	res.headers.set(
6		"Content-Security-Policy",
7		"default-src 'self'; script-src 'self' https://cdn.example.com; object-src 'none'"
8	);
9	res.headers.set("Strict-Transport-Security", "max-age=63072000; includeSubDomains; preload");
10	res.headers.set("Access-Control-Allow-Origin", "https://myapp.com");
11	res.headers.set("X-Frame-Options", "DENY");
12	res.headers.set("X-Content-Type-Options", "nosniff");
13	res.headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
14	res.headers.set("Permissions-Policy", "geolocation=(), camera=(), microphone=()");
15	res.headers.set("Cache-Control", "public, max-age=31536000, immutable");
16	return res;
17

Summary:Cookies & Headers in Middleware

• Cookies: Read, set, or delete cookies via req.cookies and res.cookies. Ideal for auth tokens, user preferences, and lightweight state.
• Headers: Modify request/response headers for analytics, debugging, caching, and security.
• Security: Apply headers like CSP, HSTS, CORS, X-Frame-Options, etc., to harden your app.
• Best Practice: Middleware can’t read request bodies — rely on cookies and headers for metadata and control.

Authentication & Authorization

9. How do you protect routes using Middleware for authentication and role-based access control (RBAC)?

In Next.js, Middleware is perfect for route protection because it allows you to inspect cookies, headers, or tokens and decide whether to allow, block, or redirect the request — making authentication and role-based access control (RBAC) one of the most powerful use cases for the Edge Runtime.

1. Authentication (checking login status)

   You typically store a session token or JWT in cookies. Middleware checks for that token, and if it’s missing/invalid, it redirects the user to a login page.

   TYPESCRIPTCopy

   1// middleware.ts
   2import { NextResponse } from "next/server";
   3import type { NextRequest } from "next/server";
   4export function middleware(req: NextRequest) {
   5	const token = req.cookies.get("token"); // session/JWT
   6	if (!token) {
   7		// Redirect to login if not authenticated
   8		return NextResponse.redirect(new URL("/login", req.url));
   9	}
   10	// Allow request to continue
   11	return NextResponse.next();
   12}
   13// Match protected routes only
   14export const config = {
   15	matcher: ["/dashboard/:path*", "/profile/:path*"], 
   16};

---

2. Role-Based Access Control (RBAC) You can store a role in the cookie/session (e.g., "admin", "user", "editor"). Middleware reads it, and checks if the user has the right permission for the route.
   TYPESCRIPTCopy

   1// middleware.ts
   2import { NextResponse } from "next/server";
   3import type { NextRequest } from "next/server";
   4export function middleware(req: NextRequest) {
   5	const token = req.cookies.get("token"); 
   6	const role = req.cookies.get("role"); // e.g., "admin" or "user"
   7	if (!token) {
   8		return NextResponse.redirect(new URL("/login", req.url));
   9	}
   10	// Example RBAC: only admins can access /admin/*
   11	if (req.nextUrl.pathname.startsWith("/admin") && role !== "admin") {
   12		return NextResponse.redirect(new URL("/unauthorized", req.url));
   13	}
   14	return NextResponse.next();
   15}
   16export const config = {
   17	matcher: ["/dashboard/:path*", "/admin/:path*"], 
   18};

Benefits of Middleware-Based RBAC

• Fast: Runs at the edge, before routing.
• Secure: Prevents access before hitting route logic.
• Scalable: Easily extendable to new roles and routes.

10. How do you handle JWT tokens or session cookies in Middleware, and what are best practices for redirecting unauthenticated users?

In Next.js Middleware, you typically handle authentication using JWT tokens or session cookies. The process starts with reading the cookie or header from the incoming request (using req.cookies.get() or req.headers.get()). For JWTs, you decode and verify the signature to ensure the token is valid and not expired. For session cookies, you check whether the cookie exists and, if needed, validate it against your session store.

If the request is unauthenticated (missing, invalid, or expired token/session), the best practice is to:

• Redirect users to your login page using NextResponse.redirect().
• Preserve the intended destination (e.g., using a redirectTo query param) so they can be sent back after logging in.
• Keep sensitive routes protected while still allowing public routes (like /login, /signup, /about) to bypass the check.

This approach ensures your app remains secure, user-friendly, and scalable at the edge.

This is how you achieve this...

Handling JWTs and session cookies in Next.js middleware is all about early interception, lightweight validation, and smart redirection — all at the edge, before your app even starts rendering.

Handling JWT Tokens or Session Cookies in Middleware

Step 1: Read the Cookie Middleware runs in the Edge Runtime, so you use request.cookies.get():

You can also use headers if your token is passed via Authorization, but cookies are more common for web apps.

Step 2: Decode or Verify the Token

You can decode the JWT to extract user info (like role or ID). But remember: Edge Runtime has limited support for Node libraries, so use lightweight or edge-compatible JWT parsers.

1import { jwtVerify } from 'jose'; // Edge-compatible
2const secret = new TextEncoder().encode(process.env.JWT_SECRET);
3const { payload } = await jwtVerify(token, secret);

Avoid using heavy libraries like jsonwebtoken unless you're sure they're edge-safe.

Step 3: Check Authentication & Role

Use the decoded payload to enforce access control:

1if (!payload || !payload.role) {
2	return NextResponse.redirect(new URL('/login', request.url));
3}
4
5if (request.nextUrl.pathname.startsWith('/admin') && payload.role !== 'admin') {
6	return NextResponse.redirect(new URL('/unauthorized', request.url));
7}

Best Practices for Redirecting Unauthenticated Users

1. Use NextResponse.redirect()

   This sends a 302 redirect to the client:

   
   

   return NextResponse.redirect(new URL('/login', request.url));

2. Preserve the Original Path

   So users can return after login:

   TYPESCRIPTCopy

   1const loginUrl = new URL('/login', request.url);
   2loginUrl.searchParams.set('redirect', request.nextUrl.pathname);
   3return NextResponse.redirect(loginUrl);

3. Scope Middleware with matcher

   Only run middleware on protected routes:

   TYPESCRIPTCopy

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

4. Avoid Redirect Loops

   
   

   Make sure /login and /unauthorized are excluded from middleware logic.

   Bonus: Modular Auth Middleware

   Split logic into reusable functions:

   
   
   TYPESCRIPTCopy

   1export async function verifyAuth(request: NextRequest) {
   2	const token = request.cookies.get('auth-token')?.value;
   3	if (!token) return false;
   4	try {
   5		const { payload } = await jwtVerify(token, secret);
   6		return payload;
   7	} catch {
   8		return false;
   9	}
   10}

   Then use it in your main middleware.ts:

   TYPESCRIPTCopy

   1const user = await verifyAuth(request);
   2if (!user) return redirectToLogin(request);

Summary: Handling JWTs & Session Cookies in Middleware

• Read tokens from cookies or headers early at the edge.
• Verify JWTs using edge-compatible libraries (like jose).
• Enforce access control based on payload (e.g., role, ID).
• Redirect unauthenticated users with NextResponse.redirect(), preserving the original path.
• Scope Middleware to protected routes only, and exclude login/unauthorized to avoid loops.
• Modularize logic (e.g., verifyAuth) for reusability across projects.

Advanced Use Cases

11. How can Middleware be used for localization, geolocation-based routing, A/B testing or feature flags, rate limiting, IP blocking, and logging requests without slowing responses?

How can Middleware be used for localization?

What Is Localization?

Localization is the process of adapting your application’s content, layout, and behavior to match the language, region, and cultural preferences of the user. It’s not just translation.

It includes:

• Translating text into different languages (e.g., English, Hindi, French)
• Formatting dates, currencies, and numbers based on locale
• Serving region-specific content (e.g., Indian promotions vs. US offers)
• Adjusting layout for right-to-left (RTL) languages like Arabic or Hebrew

How Middleware Helps with Localization in Next.js?

Middleware runs before routing, which makes it perfect for detecting and handling localization logic early in the request lifecycle.

Common Use Cases:

• Detect user locale from cookies, headers, or IP
• Redirect to locale-specific routes (e.g., /en, /hi, /fr)
• Rewrite URLs internally to serve localized content
• Set locale cookies for future requests

Example: Locale Detection & Redirect

1import { NextResponse } from 'next/server';
2import type { NextRequest } from 'next/server';
3
4export function middleware(request: NextRequest) {
5    const pathname = request.nextUrl.pathname;
6
7    // Skip static files and API routes
8    if (pathname.startsWith('/api') || pathname.includes('.')) {
9        return NextResponse.next();
10    }
11
12    // Check if locale is already in the URL
13    const locales = ['en', 'hi', 'fr'];
14    const hasLocale = locales.some((locale) => pathname.startsWith(/${locale}));
15    if (hasLocale) return NextResponse.next();
16
17    // Detect locale from cookie or header
18    const cookieLocale = request.cookies.get('locale')?.value;
19    const headerLocale = request.headers.get('Accept-Language')?.split(',')[0].slice(0, 2);
20    const rawLocale = cookieLocale || headerLocale;
21    const detectedLocale = locales.includes(rawLocale || '') ? rawLocale : 'en';
22
23    // Redirect to locale-prefixed route
24    const normalizedPath = pathname === '/' ? '' : pathname;
25    return NextResponse.redirect(new URL(/${detectedLocale}${normalizedPath}, request.url));
26}
27
28export const config = {
29    matcher: ['/((?!api|_next|favicon.ico).*)'],
30};

Best Practices

• Use cookies to persist user locale across sessions
• Fallback to browser language if no cookie is set
• Avoid redirect loops by checking if locale is already present
• Use matcher to exclude static assets and API routes

In short:

Middleware makes localization seamless by detecting language preferences and redirecting users to the right localized route, ensuring a smoother global user experience.

How can Middleware handle geolocation-based routing (serving content by user's country/region)?

What Is Geolocation-Based Routing?

In Next.js, Middleware can handle geolocation-based routing by using the request.geo object, which provides country, region, city, and latitude/longitude (only available on Vercel Edge). With this, you can decide which region-specific content or server to serve.

It’s the practice of detecting a user’s physical location (usually by IP) and then:

• Redirecting them to a region-specific version of your site
• Serving localized content (e.g., /in, /us, /uk)
• Applying country-specific logic (currency, language, legal disclaimers, etc.)

How Middleware Enables This in Next.js?

In Next.js Middleware, geolocation-based routing works by detecting the user’s location (usually through request headers like x-vercel-ip-country, x-vercel-ip-city, etc., automatically provided when deploying on Vercel Edge). Based on that information, you can decide which version of your site or content to serve.

Example: Redirect Based on Country

1// middleware.ts
2import { NextResponse } from "next/server";
3import type { NextRequest } from "next/server";
4
5const supportedRegions = new Set(['in', 'us', 'uk']);
6const fallbackRegion = 'us';
7
8export function middleware(request: NextRequest) {
9const { pathname } = request.nextUrl;
10
11// Skip static files and API routes
12if (pathname.startsWith('/api') || pathname.includes('.')) {
13	return NextResponse.next();
14}
15
16// Check if region is already in the path
17const hasRegion = Array.from(supportedRegions).some(region =>
18	pathname.startsWith('/${region}')
19);
20if (hasRegion) return NextResponse.next();
21
22// Get region from geo or fallback
23let region = request.geo?.country?.toLowerCase() || fallbackRegion;
24
25// Validate region
26if (!supportedRegions.has(region)) {
27	region = fallbackRegion;
28}
29
30// Rewrite to region-prefixed path
31const newPath = pathname === '/' ? /${region} : /${region}/${pathname};
32	return NextResponse.rewrite(new URL(newPath, request.url));
33}
34
35export const config = {
36	matcher: ['/((?!api|_next|favicon.ico).*)'],
37};

• NextResponse.rewrite() lets you serve region-specific content without changing the URL.
• NextResponse.redirect() can be used if you want to explicitly send users to a region-specific path.

Common Use Cases

• Redirect Indian users to /in
• Serve EU users from an EU data center for GDPR compliance
• Route Asian users to faster servers

Best Practices

• Always fallback gracefully if request.geo is undefined (e.g., in local dev or unsupported platforms).
• Prevent redirect loops by checking if the region is already in the path.
• Use cookies to persist the region choice if a user overrides it manually.
• Combine with localization for full geo-language routing (e.g., /in/hi, /us/en).
• Always set a fallback region (like US) so all users get content even without geo headers.

What is the difference between localization and geolocation-based routing. They sound similar but they are different?

Localization

What it is: Adats content to the user's language, culture, or preference, regardless of the physical location.

Use Case: Serve content in the right language or format.

Example:

• Browser language = fr-FR serve French version (/fr).
• User preference saved in cookies = always show Spanish, even if they're in the U.S.

Focus: Language and cultural context.

Geo-location-based routing

What it is: Detects a user's physical location (usually via IP - country/region).

Use case: Serve content or redirect based on where the user is.

Example:

• User from India - redirect to /in store.
• User from U.S. - redirect to /us store.

Focus: physical location of the user.

Key Difference:

• Localization = Where the user is.
• Geolocation = How the user wants to experience your site.

How can Middleware enable A/B testing or feature flags for experiments?

What is A/B Testing?

Middleware in Next.js runs before the response is sent, making it ideal for experiments like A/B testing or feature flag rollouts. You can decide dynamically which version of a page a user should see — all at the edge, without slowing down requests.

A/B testing is a method of comparing two versions of something — version A and version B — to see which one performs better. It's like running a controlled experiment on your users.

Goal:

To make data-driven decisions by testing changes on a small group before rolling them out to everyone.

How A/B Testing or feature flags Works in Next.js Middleware?

1. Split Your Audience

   Use middleware to randomly assign users to one of two groups:

   • Group A: Sees the original version (control)
   • Group B: Sees the new version (variant)

   You can do this by checking for a cookie and assigning one if it doesn’t exist:

   TYPESCRIPTCopy

   1export function middleware(req: NextRequest) {
   2	const experiment = req.cookies.get('ab-test')?.value
   3	if (!experiment) {
   4		const group = Math.random() < 0.5 ? 'A' : 'B'
   5		const res = NextResponse.next()
   6		res.cookies.set('ab-test', group, { path: '/', maxAge: 60 * 60 * 24 }) // 24 hours (86400 seconds)
   7		return res
   8	}
   9	return NextResponse.next()
   10}

   This ensures each user is consistently assigned to the same group across visits.

---

2. Serve Different VersionsUse NextResponse.rewrite() to serve different content based on the assigned group without changing the visible URL:

   TYPESCRIPTCopy

   1if (experiment === 'B' && req.nextUrl.pathname === '/homepage') {
   2	return NextResponse.rewrite(new URL('/homepage-variant', req.url))
   3}

   This keeps the user on /homepage but serves /homepage-variant behind the scenes.

---

3. Use Feature Flags (Optional)

   You can also integrate feature flags to toggle specific components or behaviors based on:

   • User roles (admin, contributor, guest)
   • Geographic region
   • Experiment group

   Flags can come from:

   • External services like LaunchDarkly, Split.io, or ConfigCat
   • A config file or environment variable

---

4. Measure Performance

   Track key metrics to evaluate which version performs better:

   • Click-through rate (CTR)
   • Conversion rate
   • Time on page
   • Revenue per visitor

   Use analytics tools or custom logging to capture this data per group.

---

5. Analyze and Decide

   Once enough data is collected:

   • If Group B outperforms Group A, roll out the variant to all users.
   • If not, stick with the control or test a new variant.

Feature Flags with Middleware

Feature flags let you toggle features on or off for specific users, regions, or sessions — ideal for gradual rollouts or testing new functionality.

Use Cases:

• Enable a new checkout flow for 10% of users
• Show a beta feature only to users in Canada
• Disable a feature for mobile devices

Implementation Ideas:

• Use cookies or headers to check flag status
• Combine with request.geo for region-based flags
• Rewrite or redirect to feature-specific routes

Best Practices

• Keep middleware logic minimal and fast.
• Always assign a default fallback variant.
• Use consistent user ID hash or random seed.
• Persist experiment group in cookies.
• Route users server-side to avoid flicker.
• Add custom headers for analytics tracking.
• Log experiment data for later analysis.
• Use environment variables to toggle experiments.
• Avoid client-side routing for variant decisions.
• Ensure users stay in the same group across sessions.

How can Middleware be used for rate limiting (preventing abuse/spam)?

What is Rate Limiting?

Rate limiting is a security and performance technique used to prevent abuse, spam, or denial-of-service by restricting the number of requests a client can make in a given timeframe. Middleware in Next.js is well-suited for this because it runs before the request hits your application logic, allowing you to block or throttle bad actors at the edge.

Think of it like a traffic signal:

If too many cars (requests) come at once, the signal controls the flow.

Without it, there’s a traffic jam (server overload) or accidents (abuse, spam, DDoS attacks).

How it Works in Middleware

1. Track requests per user
   • Identify clients by IP address (request.ip) or authorization token.
   • Store request counts in a fast key-value store (e.g., Upstash Redis, Vercel KV, or Edge Cache).

2. Enforce limits

   If a client exceeds the allowed requests (e.g., 100 requests/min), respond with 429 Too Many Requests.

   Otherwise, allow the request to continue.

3. Return helpful headers

   Add rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) so clients know their limits.

   Real-World Example

   • Real-World Use Cases of Rate Limiting in Middleware
   • Preventing bots from spamming login/signup forms.
   • Protecting expensive API routes (AI, DB-heavy, or third-party APIs).
   • Controlling free-tier usage in SaaS apps.
   • Throttling comment or feedback submissions to prevent spam.
   • Limiting search queries to stop excessive requests.
   • Reducing load from web scrapers or crawlers.
   • Preventing brute-force password attacks on authentication endpoints.
   • Ensuring fair usage in multiplayer games or real-time apps.
   • Avoiding overload on rate-sensitive services (e.g., payment gateways).
   • Enforcing per-user request limits for APIs with paid tiers.
   • Stopping malicious actors from DDoS-like request floods.

Best Practices for Rate Limiting in Middleware

1. Use different limits for different endpoints

   Example: Stricter limits on /login, more relaxed on /search, and almost no limits on static assets like images.

2. Account for user roles/tiers
   • Free users → tighter limits
   • Premium users → higher limits
   • Internal/admin accounts → often exempt

3. Graceful degradation, not hard blocking

   Instead of instantly blocking, you can slow down responses (e.g., introduce small delays for suspicious clients).

4. Whitelist trusted sources

   Internal APIs, monitoring services, or payment gateways may need exemptions.

5. Combine rate limiting with other security measures
   • Add CAPTCHA for login after N failed attempts.
   • Pair with bot-detection or anomaly detection.

6. Use sliding windows instead of fixed windows

   Prevents "burst attacks" where attackers send requests at the boundary of time windows.

7. Leverage edge networks

   Run rate limiting at the edge (CDN / Middleware) so abuse never reaches your origin server.

8. Monitor and log violations

   Store logs of blocked requests for later analysis (IP reputation, fraud detection, auditing).

9. Return consistent error responses

   Always respond with proper 429 Too Many Requests and meaningful retry info in headers.

10. Avoid over-restricting legitimate users

    Mobile networks often share IPs → don’t lock out an entire region because one IP misbehaves.

11. Scale limits with traffic

    On Black Friday, product launches, or viral content, adjust limits dynamically instead of hardcoding.

12. Make limits transparent to developers

    If you’re offering an API, document the rate limits clearly so clients know how to design around them.

How can Middleware block or allow traffic based on IP addresses?

What is IP Blocking?

IP blocking is a security technique that prevents specific clients (based on their IP address) from accessing your application. It’s commonly used to stop malicious actors, spammers, scrapers, or region-specific traffic.

Middleware in Next.js is perfect for this because it runs before the request hits your application logic, meaning you can deny bad traffic right at the edge without wasting server resources.

It means rejecting requests from specific IP addresses or ranges before they reach your app. It is a powerful way to prevent access from unwanted sources — whether you're defending against spam, abuse, or region-specific restrictions.

Think of it like a security guard at the gate:

If the visitor (IP) is on the blacklist, they’re denied entry.

If they’re trusted, they’re let in without disturbing the building inside.

How It Works in Middleware

1. Identify the client’s IP

   • Use request.ip in Next.js Middleware (works on Vercel Edge Network).
   • For custom deployments, you may need to extract it from x-forwarded-for headers.

2. Check against a blocklist or allowlist

   • Static list (array in code).
   • Dynamic list (stored in Redis, KV, or database).

3. Decide the response

   • If blocked → return 403 Forbidden or redirect to an error page.
   • If allowed → let the request continue.

Example

1import { NextResponse } from 'next/server';
2import type { NextRequest } from 'next/server';
3
4// List of blocked IPs (can be expanded or loaded from external source)
5const blockedIPs = new Set([
6	'192.168.1.10',
7	'203.0.113.42',
8	'::ffff:127.0.0.1', // IPv6-mapped IPv4
9]);
10
11export function middleware(request: NextRequest) {
12	const ip =
13	request.ip || // Vercel Edge
14	request.headers.get('x-forwarded-for')?.split(',')[0]?.trim(); // Fallback
15
16	if (ip && blockedIPs.has(ip)) {
17		return new Response('Access Denied: Your IP is blocked', { status: 403 });
18	}
19
20	return NextResponse.next();
21}
22
23export const config = {
24	matcher: ['/((?!api|_next|favicon.ico).*)'],
25};

Real-World Use Cases of IP Blocking in Middleware

• Blocking known malicious IPs (from security feeds).
• Preventing DDoS attackers or repeated brute-force attempts.
• Enforcing geo-restrictions (e.g., service only available in certain countries).
• Banning abusive users by IP after multiple violations.
• Blocking spammers/bots from submitting forms.
• Protecting APIs from unauthorized scrapers/crawlers.
• Limiting access to internal dashboards (only allow office IPs).
• Temporary quarantine for suspicious IP ranges.

Best Practices for IP Blocking in Middleware

1. Maintain separate allowlist and blocklist

   Always prioritize allowlist (trusted IPs) over blocklist checks.

2. Avoid hardcoding large lists in code

   Store blocklists in Redis, Vercel KV, or external API → update without redeploys.

3. Use CIDR ranges when needed

   Block entire ranges for abusive networks (e.g., 192.168.0.0/24).

4. Combine with rate limiting

   If an IP violates rate limits repeatedly, auto-add to blocklist.

5. Return clear error codes

   Use 403 Forbidden or 451 Unavailable for Legal Reasons for geo-blocks.

6. Be careful with shared IPs

   Mobile carriers or corporate networks share IPs → blocking them may affect legitimate users.

7. Log all blocked requests

   Helps with incident analysis, security audits, and adjusting policies.

8. Dynamic expiration

   Auto-expire blocked IPs after some time to avoid permanent bans on possibly innocent users.

Notes

• On platforms like Vercel, request.ip is automatically populated at the edge.
• For self-hosted or custom setups, use headers like x-forwarded-for or x-real-ip.

What is the difference between Rate Limiting and IP blocking.

Rate Limiting

What it is: Restricts how many requests a user/IP/client can make in a certain time window.

Goal: Prevent abuse (e.g., API spam, brute force attacks) without blocking legitimate traffic.

Example:

• Allow 100 requests per minute per IP.
• If limit exceeded respond with 429 Too Many Requests.

Behavior: Temporary once the time window resets, requests are allowed again.

IP Blocking

What it is: Completely denies all requests from a specific IP (or range of IPs).

Goal: Block known attackers, malicious bots, or unwanted traffic.

Example:

• Ban traffic from 203.0.113.45.
• All requests are rejected no matter how few.

Behavior: Permanent (until unblocked).

Key Difference

• Rate Limiting = "You can't go faster than X requests per second." (throttle).
• IP Blocking = "You can't go at all." (ban).

How can Middleware log requests (for analysis, monitoring, or debugging) without slowing responses?

Logging must be done carefully — otherwise, you risk adding latency. The secret is fire-and-forget logging: capture → dispatch → move on.

Key Principles

1. Capture Only Lightweight Metadata

   Log essentials only:

   • IP address
   • Path & method
   • Timestamp
   • User-Agent
   • Geo (request.geo)

   Avoid heavy operations like DB queries, API calls, or file writes.

2. Asynchronous / Fire-and-Forget Logging

   Use a non-blocking approach: send logs but don’t wait for the response.

   Example:

   TYPESCRIPTCopy

   1import { NextResponse } from 'next/server';
   2import type { NextRequest } from 'next/server';
   3import { sendLog } from './lib/logger'; // Async logging utility
   4
   5export function middleware(request: NextRequest) {
   6	// Collect minimal request metadata
   7	const logData = {
   8		ip: request.ip,
   9		path: request.nextUrl.pathname,
   10		method: request.method,
   11		timestamp: Date.now(),
   12		userAgent: request.headers.get('user-agent'),
   13	};
   14
   15	// Fire-and-forget: don’t await
   16	sendLog(logData);
   17	return NextResponse.next();
   18}

   Where sendLog() might:

   • Push logs to a queue (Redis, Kafka, SQS, Upstash)
   • Stream to a logging service (Logtail, Datadog, Sentry)
   • Write to an external API

3. Offload Work to External Pipelines

   • Middleware only captures & forwards.
   • Processing (aggregation, analytics, anomaly detection) happens in background workers or log processors.

4. Use Batching or Buffering (Advanced)

   For high-volume traffic, buffer logs and flush periodically.

   Reduces network overhead and improves throughput.

5. Sanitize Sensitive Data

   Never log raw:

   • Passwords
   • Tokens
   • PII (personally identifiable info)

   Apply redaction/masking before dispatching.

6. Leverage Edge-Native Logging Solutions

   • Vercel Analytics
   • Edge Config for fast storage
   • Third-party observability tools optimized for edge runtimes

Best Practice Summary

• Middleware should behave like a CCTV camera:
• Observe and forward requests instantly.
• Don’t block responses.
• Let downstream systems handle the heavy lifting.

Performance & Deployment

12. What are the performance implications of running Middleware at the edge, how does it interact with caching and CDNs on Vercel, what are the code size limits, and how can performance bottlenecks be avoided?

What does it mean to run Middleware at the edge in Next.js, and how is it different from server-side middleware?

Running Middleware at the edge in Next.js means your code executes globally, close to users, giving ultra-low latency and fast request handling. However, you trade away the full power of Node.js for a lighter, faster, restricted environment.

In other words........

Running Middleware at the edge in Next.js means executing request-handling logic on globally distributed servers — called Edge Locations or Points of Presence (PoPs) — that are physically closer to the user. This is a major shift from traditional server-side middleware, which runs in centralized data centers or serverless functions.

What Is Edge Middleware?

Edge Middleware in Next.js:

• Runs on platforms like Vercel’s Edge Network
• Executes before routing and caching
• Is designed for ultra-low latency, personalization, and request shaping
• Uses WebAssembly-like isolates for near-instant execution (no cold starts)

Use Cases:

• Geo-based redirects
• A/B testing
• Feature flag evaluation
• Security headers
• Authentication checks

What Is Server-Side Middleware?

Server-side middleware:

• Runs in a centralized server or serverless function
• Has access to full Node.js APIs (e.g., fs, crypto, net)
• Can perform heavy computation, access databases, and read request bodies
• Typically used in API routes, Express.js apps, or custom server setups

Difference from Server-side Middleware

Location:

• Edge → runs at global PoPs near the user
• Server-side → runs in a single region/data center (e.g., US-East-1 AWS)

Latency:

• Edge → much lower round-trip time (fast redirects, personalization)
• Server-side → higher latency for users far from the server

Environment:

• Edge → restricted runtime (no Node.js APIs, file system, direct DB access)
• Server-side → full Node.js environment, can run heavier logic and access backend resources

Startup:

• Edge → near-zero cold start (milliseconds)
• Server-side → can suffer 200–300ms cold starts in serverless functions

Key Differences

What is the main performance benefits of running Middleware closer to the users?

Running Middleware closer to users — specifically at the edge — unlocks a suite of performance benefits that can dramatically improve responsiveness, scalability, and user experience

Performance Benefits of Edge Middleware

1. Lower Latency (Faster Responses)

   • Requests don’t need to travel all the way to your origin server.
   • The middleware runs at a nearby edge location, reducing round-trip time.
   • Example: A user in India gets a redirect or auth check from an India-based PoP instead of hitting a US server.

2. Faster Redirects and Rewrites

   URL-based logic (auth gating, A/B testing, geo-routing) executes immediately at the edge, often before the request even reaches your app.

3. Improved Scalability

   • Work is distributed across many edge nodes, reducing load on a central server.
   • Middleware runs independently at each edge, handling millions of requests concurrently without bottlenecks.

4. Reduced Cold Start Penalties

   • Edge Middleware runs in lightweight isolates (not full Node.js processes).
   • This gives near-instant execution (a few ms), unlike serverless functions which may have 200–300ms cold starts.

5. Better User Experience Globally

   • Since edge nodes are worldwide, users in different regions all get equally fast responses.
   • No more “slow for Asia/Africa users, fast for US users” problem.

6. Optimized Caching Integration

   • Middleware can run before a CDN cache lookup.
   • This means you can tailor caching rules (e.g., vary by country, auth, or device type) without hitting the origin.

In simple words

Edge Middleware is like a smart traffic cop stationed at every intersection — fast, local, and decisive. It enables personalization, security, and routing logic to happen before your app even starts rendering, all while keeping latency low and scalability high.

At the end

Edge Middleware gives you speed, scalability, and consistency worldwide by moving lightweight request handling closer to users instead of a single origin server.

What trade-offs exist between the edge runtime (lightweight isolates) and the Node.js runtime?

Edge Runtime vs Node.js Runtime: Trade-Offs

Architectural Implications

Edge Runtime Strengths:

• Ideal for geo-aware logic, A/B testing, feature flags, and early redirects
• Great for stateless, lightweight, and fast-executing logic
• Reduces latency for global users by running in nearby PoPs

Edge Runtime Limitations:

• No access to request body — can’t parse JSON or form data
• No direct database access or file system operations
• Limited package support — must use edge-compatible libraries

Node.js Runtime Strengths:

• Full access to Node.js APIs and ecosystem
• Can handle complex business logic, data fetching, and file manipulation
• Suitable for API routes, server components, and heavy computation

Node.js Runtime Limitations:

• Higher latency due to centralized execution
• Cold starts can affect performance under load
• Requires careful scaling and infrastructure management

When to Use Each

• Use Edge Runtime for:

  • Middleware
  • Early request shaping
  • Geo-based personalization
  • Fast redirects and rewrites



• Use Node.js Runtime for:

  • API routes
  • Database queries
  • File uploads/downloads
  • Auth token validation with request body

Practical Guideline

• Use Edge Runtime for fast, lightweight, globally distributed logic (auth checks, redirects, rewrites, feature flags, geo-routing).
• Use Node.js Runtime for heavy, complex, or stateful operations (DB queries, file processing, AI tasks).
• In real-world apps → Combine both: Middleware (Edge) for request filtering + API Routes (Node) for business logic.
• In short: Edge = speed + scale, Node = power + flexibility.

How does Middleware at the edge interacts with caching and CDNs on Vercel?

In Next.js on Vercel, Middleware at the edge plays a pivotal role in how requests interact with CDN caching — it does so by modifying requests and responses to enable fast, personalized, and scalable apps.

How .... ??

1. Runs before the cache

   • Middleware executes before CDN caching is applied.
   • That means every request hits the Middleware first, even if the content is already cached.
   • This is why Middleware is great for request inspection (auth, geo-routing, feature flags).

2. Can customize caching behavior

   Middleware can modify request/response headers (Cache-Control, Vary, etc.).

   Example: you could serve different cached versions of a page per country, language, or A/B test group.

   This enables personalized caching instead of one-size-fits-all.

3. Global Distribution Benefits

   Because Middleware runs on Vercel’s Edge Network (CDN PoPs), caching rules are enforced closer to users.

   This reduces latency and makes personalized caching scalable.

4. Potential Performance Trade-Offs

   • Since Middleware always runs before cache, it adds overhead to every request (even cached ones).
   • If Middleware does too much work, it can negate CDN speed benefits.
   • Heavy logic (like DB queries) should not be in Middleware — it slows everything, including cache hits.

5. Use Cases for Cache + Middleware Together

   • Geo-based caching → Store different versions of a page per region.
   • A/B testing → Cache multiple variants of the same page for different test groups.
   • Auth-gated static content → Use Middleware to check auth, then serve cached content accordingly.

Best Practices

• Keep Middleware lightweight to preserve CDN speed
• Use Cache-Control headers to fine-tune caching behavior
• Avoid rewriting static asset paths unless necessary
• Combine Middleware with Incremental Static Regeneration (ISR) for dynamic yet cacheable content
• Use cookies or headers to segment cache for personalized experiences

In short:

• Middleware is the “gatekeeper” before CDN cache.
• It can shape caching strategy (headers, variants, personalization).
• But if overused, it can slow down even cached responses — so keep Middleware lightweight and cache-aware.

Summary

• Edge Middleware is like a smart filter that runs before your CDN cache — shaping requests, injecting logic, and optionally modifying cache behavior. It’s powerful, but must be used with care: too much logic here can slow down even cached pages. The key is to balance personalization with performance, and always test how Middleware affects cache hit rates.

What are the code size and runtime limitations of edge Middleware?

Edge Middleware in Next.js has strict limitations compared to running in a full Node.js server.

Code Size Limitations

Bundle size is small → Edge functions (including Middleware) are designed to load super fast in V8 isolates.

• Vercel enforces a 1 MB uncompressed limit per Edge Function (Middleware counts as one).
• This means no heavy npm packages (like sharp, bcrypt, or puppeteer).

You should stick to lightweight utilities, avoid large dependencies, and prefer native Web APIs.

Runtime Environment

No full Node.js runtime → It’s not Node.js; it’s more like a browser-like V8 isolate.

• No native Node APIs (e.g., fs, net, child_process).
• Only Web-standard APIs (like fetch, Request, Response, URL, TextEncoder).

Performance Implications

• Cold starts are faster than Node.js serverless functions, but you must keep the logic minimal.
• Middleware runs on every request it matches, so heavy logic will multiply performance costs.

Best Practices to Avoid Bottlenecks

1. Keep the code under ~500 KB (after tree-shaking) if possible.
2. Use Middleware only for fast, conditional logic (auth checks, redirects, A/B testing, geolocation).
3. Use external KV stores (like Vercel KV or Redis) instead of bloating Middleware with state.

In short:

Edge Middleware must be lightweight, stateless, and fast, otherwise you’ll run into limits or slow down every request.

Testing & Debugging

13. How do you test Middleware locally (including simulating the Edge Runtime), handle errors in production, debug async operations, and avoid common mistakes?

How can you test Next.js Middleware locally, and what options exist to simulate the Edge Runtime environment?

1. Local Testing in Next.js Dev Mode

   When you run next dev, Middleware does run locally, but by default it executes in the Node.js runtime, not the Edge Runtime.

   This means you can test logic like request inspection, rewrites, and redirects — but the behavior won’t be 100% identical to production.

   For example, Node APIs may appear available locally, but they will break in production because Edge Middleware runs in a restricted environment (no native Node APIs).

2. Using vercel dev for Closer Simulation

   Running vercel dev gives you a closer approximation of the Edge Runtime, because it tries to mimic Vercel’s production environment.

   Still, it’s not a full isolate-based simulation — but it’s better than plain next dev if you want to catch runtime differences earlier.

3. Simulating Edge Runtime via Wrangler (Advanced)

   Since Vercel Edge Runtime is based on Web Standard APIs (like Cloudflare Workers, Deno), you can simulate the environment with tools like:

   • Wrangler (Cloudflare Workers CLI)
   • Miniflare (local Cloudflare Workers emulator)

   These let you test under restrictions similar to the Edge Runtime (no fs, limited crypto, etc.), helping you catch incompatibilities.

4. Best Practices for Testing Middleware

   • Stick to Web APIs: Always use Request, Response, URL, Headers, fetch — never Node-specific modules.
   • Test Locally + Deploy Early: Because true Edge Runtime behavior only happens on Vercel’s Edge, deploy test branches early to validate.
   • Unit Test Pure Logic: If Middleware has business logic (auth checks, feature flags), abstract it into pure functions you can test with Jest/Node.

In short:

You can test Middleware locally with next dev, but it’s Node-based. vercel dev is closer but not perfect. For true simulation, use standards-based environments (Wrangler/Miniflare). Ultimately, nothing beats testing on Vercel Edge itself, so deploy early and often.

What are the best pratices for handling errors in Middleware when running in production?

Edge Middleware runs before your app and CDN caching, so if it fails, it can break the entire request flow. To keep apps reliable and fast, error handling needs to be fail-safe, lightweight, and production-ready.

1. Fail Fast, Fail Gracefully

   Middleware should be lightweight — no heavy DB queries or blocking operations.

   If something goes wrong, don’t crash the pipeline. Instead, return a safe fallback:

   • Redirect to /login for missing auth
   • Show a /500 or maintenance page
   • Or simply let the request continue with NextResponse.next()
   TYPESCRIPTCopy

   1import { NextResponse } from "next/server";
   2
   3export function middleware(req: Request) {
   4	try {
   5		if (!req.headers.get("authorization")) {
   6			return NextResponse.redirect(new URL("/login", req.url));
   7		}
   8		return NextResponse.next();
   9	} catch (err) {
   10		console.error("Middleware error:", err);
   11		return NextResponse.redirect(new URL("/500", req.url));
   12	}
   13}

2. Use Try-Catch Strategically

   • Wrap only risky logic (auth decoding, API calls, geo parsing).
   • Don’t swallow every error blindly — keep the scope tight.
   TYPESCRIPTCopy

   1export function middleware(request: NextRequest) {
   2	try {
   3		const token = request.cookies.get("auth-token")?.value;
   4		// verify token here
   5	} catch (error) {
   6		console.error("Auth check failed:", error);
   7		return new Response("Unauthorized", { status: 401 });
   8	}
   9	return NextResponse.next();
   10}

3. Return Meaningful Status Codes

   • 401 → Unauthorized (missing/invalid token)
   • 403 → Forbidden (valid but no access)
   • 429 → Too Many Requests (rate limiting)
   • 500 → Unexpected failure

   Clear codes help clients and downstream systems handle errors properly.

4. Logging & Monitoring

   • Errors in Middleware don’t show in the browser — you need external logging.
   • On Vercel: console.error() pipes into Edge logs.
   • For production monitoring, use edge-compatible tools like:
     • Sentry (Edge SDK)
     • Datadog
     • Logtail
     • Upstash Kafka

   Always send logs asynchronously (“fire-and-forget”) so they don’t block responses.

   TYPESCRIPTCopy

   1sendErrorLog({
   2	message: error.message,
   3	path: request.nextUrl.pathname,
   4	ip: request.ip,
   5});

5. Handle Async Failures Properly

   • Wrap async calls in try/catch.
   • Never assume external APIs will succeed.
   • Always provide fallbacks.
   TYPESCRIPTCopy

   1export async function middleware(req: Request) {
   2	try {
   3		const res = await fetch("https://api.example.com/feature-flags");
   4		if (!res.ok) throw new Error("Failed to fetch flags");
   5		return NextResponse.next();
   6	} catch (err) {
   7		console.error("Edge fetch failed:", err);
   8		return NextResponse.next(); // fallback to default behavior
   9	}
   10}

6. Avoid Breaking the CDN

   • Middleware runs before CDN caching.
   • If it throws, you may cause cache misses and hurt performance.
   • When in doubt, fall back to NextResponse.next() to preserve caching.

7. Graceful Fallbacks

   Always check for optional runtime data (like request.geo) and default safely:

   TYPESCRIPTCopy

   1const country = request.geo?.country?.toLowerCase() || "us";

8. Don’t Rely on Node.js Error Objects

   • Edge runtime is not Node.js.
   • error.stack or Node-specific error properties may not exist.

9. Test Error Scenarios in Staging

   • Don’t just test the happy path. Simulate:

     • Missing headers
     • API downtime
     • Invalid tokens
   • Deploy to a staging Vercel project before production rollout.

Summary

Error handling in Edge Middleware is about resilience without overengineering.

• Keep middleware lightweight.
• Catch only necessary errors, return meaningful status codes.
• Use structured logging with external monitoring.
• Wrap async logic safely and fallback gracefully.
• Never let an error crash caching or request flow.

If Middleware fails, users should still see something useful — not a blank page.

How do you debug async operations inside Middleware, given the constraints of the Edge Runtime?

Debugging async operations inside Next.js Middleware — especially within the Edge Runtime — requires a different mindset than traditional Node.js debugging. Since the Edge Runtime is lightweight, stateless, and restricted, you need to lean on non-blocking techniques, external observability, and smart instrumentation.

Key Constraints of Edge Middleware

• No access to Node.js APIs (e.g., fs, process, child_process)
• No synchronous I/O or blocking operations
• No request body access
• Limited debugging tools (no breakpoints, no stack traces)
• Only supports Web APIs like fetch, console, and TextEncoder

1. Use Console Logging Wisely Since you don’t have Node.js debugging tools, console.log, console.error, and console.time are your main allies. Logs from Middleware show up in Vercel Edge Logs in production.

   
   

   Example:

   TYPESCRIPTCopy

   1export async function middleware(req: Request) { 
   2	console.time("feature-flags"); 
   3	try { 
   4		const res = await fetch("https://api.example.com/feature-flags"); 
   5		console.log("Fetch status:", res.status); const data = await res.json(); 
   6		console.log("Feature flags:", data); return NextResponse.next(); 
   7	} catch (err) { 
   8		console.error("Middleware async error:", err); 
   9		return NextResponse.next(); 
   10	} finally { 
   11		console.timeEnd("feature-flags"); 
   12	} 
   13} 

2. Use Try-Catch Around Async Calls Always wrap await fetch() or token validation in try/catch. Edge errors won’t propagate to the browser — so logging and safe fallbacks are critical.

   Example:

   TYPESCRIPTCopy

   1try { 
   2	const response = await fetch(apiUrl, { cache: "no-store" }); 
   3	if (!response.ok) throw new Error("API request failed"); 
   4} catch (err) { 
   5	console.error("Async operation failed:", err); 
   6	return NextResponse.next(); // fallback 
   7}

3. Fire-and-Forget Error Reporting If you need structured debugging beyond logs, send errors to an Edge-compatible logging service (Sentry Edge SDK, Logtail, Upstash Kafka). Do not await these calls — it will slow down your Middleware.

   
   

   Example:

   TYPESCRIPTCopy

   1// fire-and-forget 
   2
   3sendErrorReport({ 
   4	message: err.message, 
   5	url: req.url, 
   6	time: Date.now(), 
   7});

4. Use event.waitUntil() for Fire-and-Forget Logging

   This lets you run async operations without delaying the response — ideal for logging, analytics, or background tasks.

   TYPESCRIPTCopy

   1export function middleware(req: NextRequest, event: NextFetchEvent) {
   2	event.waitUntil(
   3		fetch('https://my-logging-service.com', {
   4			method: 'POST',
   5			body: JSON.stringify({ path: req.nextUrl.pathname }),
   6		})
   7	);
   8
   9	return NextResponse.next();
   10}

   This is the Edge Runtime’s version of “background tasks” — it won’t block the response.

5. Use External Logging Services

   Since you can’t write to disk or inspect stack traces, push logs to:

   • Logtail (structured logs)
   • Upstash Kafka (event streaming)
   • Sentry (error tracking)
   • Datadog (observability)

   These services let you inspect logs across regions and timeframes.

6. Debug With Staging Environments

   • Don’t debug async issues in production.
   • Deploy to a staging project on Vercel and inspect Edge Logs with real requests.
   • Simulate API downtime, slow responses, or invalid tokens to test fallbacks.

Summary table

What are the most common mistakes developers make with Middleware, and how can they be avoided?

Middleware in Next.js (especially under the Edge Runtime) is powerful but very easy to misuse. Here’s a breakdown of the most common mistakes developers make and how to avoid them

Common Middleware Mistakes in Next.js & How to Avoid Them

1. Using Middleware for Heavy Computation

   Mistake:

   Performing expensive tasks like image processing, database queries, or large data fetching inside Middleware.

   
   

   Why it’s bad:

   Middleware executes on every request at the edge, before CDN caching. Heavy work increases latency globally.

   
   

   Fix:

   Keep Middleware lean — offload heavy tasks to API routes, server components, or background jobs.




2. Accessing the Request Body

   Mistake:

   Trying to read JSON or form data in Middleware.

   
   

   Why it’s bad:

   The Edge Runtime doesn’t allow request body access (req.body is unavailable).

   
   

   Fix:

   Use query params, cookies, or headers for Middleware logic. Parse the body later in API routes.




3. Calling External APIs Directly (Improperly)

   Mistake:

   Awaiting external API calls inside Middleware.

   
   

   Why it’s bad:

   Adds latency, blocks the edge runtime, and can fail silently.

   
   

   Fix:

   • For critical data, move fetch calls to server functions.
   • For non-essential calls (logging, analytics), use event.waitUntil() to run in the background.



4. Skipping Fallbacks (Geo, Cookies, API Failures)

   Mistake:

   Assuming request.geo, cookies, or API calls always succeed.

   
   

   Why it’s bad: These

   values can be undefined (e.g., in local dev or unsupported regions). API downtime may break all requests.

   
   

   Fix:

   Always provide a safe fallback, e.g.:

   • const country = request.geo?.country?.toLowerCase() || 'us';
   • Or return NextResponse.next() if data isn’t available.



5. Not Validating Redirects / Rewrites

   Mistake:

   Redirecting without checking conditions.

   
   

   Why it’s bad:

   Causes infinite loops or unnecessary hops.

   
   

   Fix:

   Add guards:

   if (pathname.startsWith(/${locale})) return NextResponse.next();




6. Overloading Middleware with Multiple Concerns

   Mistake:

   Mixing authentication, geo-routing, logging, and feature flags into one big file.

   
   

   Why it’s bad:

   Harder to maintain, debug, and optimize.

   
   

   Fix:

   Split logic into small utilities and import them into middleware.ts. Keep Middleware modular and focused.




7. Ignoring CDN & Caching Behavior

   Mistake:

   Adding logic that runs for every request, even cached ones.

   
   

   Why it’s bad:

   Breaks caching, increasing latency unnecessarily.

   
   

   Fix:

   Be caching-aware — only use Middleware when personalization or dynamic routing is truly required.




8. Using Unsupported Node.js APIs

   Mistake:

   Importing Node-only modules like fs, process, or crypto.

   
   

   Why it’s bad:

   The Edge Runtime only supports Web APIs — Node APIs will crash.

   
   

   Fix:

   Use edge-compatible alternatives like:

   • crypto.subtle (Web Crypto) instead of Node crypto
   • jose for JWT handling
   • URL and TextEncoder for parsing and encoding



9. Forgetting Regional Consistency

   Mistake:

   Relying on local state in Middleware (e.g., writing to memory or expecting region-specific data).

   
   

   Why it’s bad:

   Middleware runs globally in multiple regions — state won’t sync.

   
   

   Fix:

   Use global stores like Vercel KV, Redis, or Upstash for consistent data across regions.




10. Debugging Only in Production

    Mistake:

    Skipping proper staging tests, relying on real users to reveal bugs.

    
    

    Why it’s bad:

    Bugs in Edge Middleware are harder to trace and may harm real users.

    
    

    Fix:

    Always test in staging with Vercel Edge Logs or external logging (Sentry, Logtail, Datadog). Simulate failures (invalid tokens, API downtime).

Summary Table — Middleware Mistakes

Integration & Best Practices

14. How do you combine Middleware with API routes, chain multiple Middleware functions for complex logic, make Middleware reusable across projects, and in what real-world scenarios does Middleware outperform SSR or API routes?

How can Middleware and API routes be combined effectively to handle request validation, authentication, or preprocessing?

In Next.js, Middleware provides fast, edge-side filtering and shaping, while API routes handle deeper validation and business logic. Together, they enable secure and performant request pipelines.

1. Use Middleware for Early Filtering (Edge Gatekeeping)

   Middleware runs before routing and CDN caching, making it ideal for lightweight filtering:

   • Checking for presence of auth/session tokens
   • Redirecting unauthenticated users
   • Blocking requests from banned IPs or regions
   • Injecting headers/cookies for downstream logic
   TYPESCRIPTCopy

   1// middleware.ts 
   2import { NextResponse } from "next/server"; 
   3import type { NextRequest } from "next/server"; 
   4export function middleware(request: NextRequest) { 
   5	const token = request.cookies.get("auth-token")?.value; 
   6	if (!token) { 
   7		return NextResponse.redirect(new URL("/login", request.url)); 
   8	} 
   9	return NextResponse.next(); 
   10}

   Benefit: Invalid or unauthenticated requests are stopped early, saving compute and avoiding unnecessary API route execution.

2. Use API Routes for Deep Validation & Business Logic

   Once Middleware passes the request through, API routes handle the heavier work:

   • Decoding and verifying JWTs
   • Validating request bodies
   • Querying databases
   • Enforcing role-based access control (RBAC)
   TYPESCRIPTCopy

   1// /pages/api/profile.ts 
   2import { verifyToken } from "@/lib/auth"; 
   3
   4export default async function handler(req, res) { 
   5	try { 
   6		const token = req.cookies["auth-token"]; 
   7		const user = await verifyToken(token); 
   8		if (!user) { 
   9			return res.status(401).json({ error: "Unauthorized" }); 
   10		}
   11		res.status(200).json({ user }); 
   12	} catch (err) { 
   13		res.status(500).json({ error: "Internal Server Error" }); 
   14	} 
   15}

   Benefit: Heavy or sensitive operations (DB, token decoding, RBAC) stay server-side, not at the edge.

3. Preprocessing with Metadata Injection Middleware can enrich requests before they hit API routes — useful for adding geo, feature flags, or request IDs.

   TYPESCRIPTCopy

   1// middleware.ts 
   2import { NextResponse } from "next/server"; 
   3import type { NextRequest } from "next/server"; 
   4
   5export function middleware(req: NextRequest) { 
   6	const country = req.geo?.country || "unknown"; 
   7	const requestHeaders = new Headers(req.headers); 
   8	requestHeaders.set("x-country", country); 
   9	
   10	return NextResponse.next({ request: { headers: requestHeaders }, }); 
   11}

   TYPESCRIPTCopy

   1// /pages/api/hello.ts 
   2export default function handler(req, res) { 
   3	const country = req.headers["x-country"]; 
   4	res.status(200).json({ message: Hello from ${country} }); 
   5}

   Benefit: API routes don’t need to repeatedly resolve geo/flags — Middleware sets it once globally.

4. Reusable Middleware Wrappers for API Routes

   For consistency, wrap API routes with reusable middleware-style helpers (like apiHandler) to centralize validation, error handling, and preprocessing.

   TYPESCRIPTCopy

   1// /lib/api-handler.ts 
   2export function apiHandler(handler) { 
   3	return async (req, res) => { 
   4		try { 
   5			await jwtMiddleware(req, res); 
   6			// custom auth check 
   7			await handler(req, res); 
   8		} catch (err) {
   9			errorHandler(err, res); // central error handling 
   10		} 
   11	}; 
   12}

   TYPESCRIPTCopy

   1// /pages/api/data.ts 
   2import { apiHandler } from "@/lib/api-handler"; 
   3async function getData(req, res) { 
   4	const data = await fetchDataFromDB(); 
   5	res.status(200).json(data); 
   6} 
   7		
   8export default apiHandler(getData);

   Benefit: Reduces boilerplate — every API route automatically enforces the same policies.

5. Logging & Monitoring Across Both Layers

   • Middleware: Use event.waitUntil() or fire-and-forget logging to avoid blocking responses.
   • API Routes: Integrate with tools like Sentry, Datadog, or Logtail for deep observability.
   TYPESCRIPTCopy

   1// middleware.ts 
   2export function middleware(req: NextRequest, event: NextFetchEvent) { 
   3	event.waitUntil( fetch("https://my-logging-service.com", { 
   4		method: "POST", body: JSON.stringify({ path: req.nextUrl.pathname }), 
   5		}) 
   6	); 
   7	return NextResponse.next(); 
   8} 

   Benefit: Unified logging — lightweight logs at the edge + detailed backend tracing.

Final Takeaway

• Middleware = fast, edge-side filter for validation, shaping, and early rejection.

• API Routes = heavy-duty backend for DB access, RBAC, and sensitive logic.

• Together → a secure, efficient, and maintainable request flow.

Use Middleware when you need edge performance, API routes when you need backend power, and combine both when requests require early filtering + deep processing.

What are the best practices for chaining multiple Middleware functions together to manage complex logic without making the codebase messy?

Chaining multiple Middleware functions can get messy fast — especially with auth, geo-routing, logging, headers, and feature flags. The key is to modularize each concern and use a pipeline (stack/chain) pattern to compose them in order.

1. Use Middleware Factories (Higher-Order Functions)

   Factories wrap and extend Middleware, returning a new one. This allows clean composition (like functional pipes).

   TYPESCRIPTCopy

   1// types.ts
   2import { NextMiddleware } from "next/server";
   3export type MiddlewareFactory = (next: NextMiddleware) => NextMiddleware;




2. Create Modular Middleware Units

   Keep each Middleware focused on a single task:

   TYPESCRIPTCopy

   1// withAuth.ts
   2import { NextResponse } from "next/server";
   3import type { NextMiddleware } from "next/server";
   4
   5export const withAuth: MiddlewareFactory = (next) => (req) => {
   6	const token = req.cookies.get("auth-token")?.value;
   7	if (!token) {
   8		return NextResponse.redirect(new URL("/login", req.url));
   9	}
   10	return next(req);
   11};

   TYPESCRIPTCopy

   1// withGeoRedirect.ts
   2import { NextResponse } from "next/server";
   3
   4export const withGeoRedirect: MiddlewareFactory = (next) => (req) => {
   5	const country = req.geo?.country?.toLowerCase();
   6	if (country === "in") {
   7		return NextResponse.redirect(new URL("/in", req.url));
   8	}
   9	return next(req);
   10};




3. Compose with a stackMiddleware

   The stack approach is functional and elegant:

   TYPESCRIPTCopy

   1// stackMiddleware.ts
   2import type { NextMiddleware } from "next/server";
   3import { MiddlewareFactory } from "./types";
   4
   5export function stackMiddleware(middlewares: MiddlewareFactory[]): NextMiddleware {
   6	return middlewares.reduceRight(
   7		(next, middleware) => middleware(next),
   8		(req) => new Response(null, { status: 200 }) // fallback
   9	);
   10}

   Alternatively, for simplicity, you can use an imperative chain:

   TYPESCRIPTCopy

   1// chain.ts
   2import { NextResponse } from "next/server";
   3import type { NextRequest } from "next/server";
   4
   5export type MiddlewareFn = (req: NextRequest) => NextResponse | void;
   6
   7export function chain(...fns: MiddlewareFn[]) {
   8	return (req: NextRequest) => {
   9		for (const fn of fns) {
   10			const result = fn(req);
   11			if (result) return result; // early exit
   12		}
   13	return NextResponse.next();
   14	};
   15}

   • Use stackMiddleware when you like functional composition.
   • Use chain when you prefer a simpler, "first-return-wins" execution model.



4. Apply the Stack in middleware.ts

   Keep your entry Middleware declarative and clean:

   TYPESCRIPTCopy

   1// middleware.ts
   2import { stackMiddleware } from "./middlewares/stackMiddleware";
   3import { withAuth } from "./middlewares/withAuth";
   4import { withGeoRedirect } from "./middlewares/withGeoRedirect";
   5import { withLogging } from "./middlewares/withLogging";
   6
   7export const middleware = stackMiddleware([
   8	withLogging,
   9	withGeoRedirect,
   10	withAuth,
   11]);
   12
   13export const config = {
   14	matcher: ["/((?!api|_next|favicon.ico).*)"], // scope it
   15};



5. Additional Tips
   • Order matters: Place filters (geo, IP block) first, then deeper logic (auth, feature flags).
   • Keep it lean: Only handle early rejection, header shaping, and light metadata injection.
   • Push heavy work (DB queries, JWT decoding) to API routes or server components.
   • Log async: Use event.waitUntil() for logging/analytics so you don’t block requests.
   • Test in isolation: Each unit should be independently testable before composing.