Request modification in NextJS - Step-by-Step Execution

Concept Flow - Request modification

Client sends request

↓

Next.js Middleware intercepts

↓

Modify request (headers, url, etc.)

↓

Forward modified request

↓

Next.js Route Handler processes

↓

Response sent back to client

The client request is intercepted by Next.js middleware, which modifies it before forwarding to the route handler for processing.

Execution Sample

NextJS

import { NextResponse } from 'next/server';

export function middleware(request) {
  const url = request.nextUrl.clone();
  url.pathname = '/new-path';
  return NextResponse.rewrite(url);
}

This middleware intercepts requests and rewrites the URL path to '/new-path' before continuing.

Execution Table

Step	Action	Request URL	Modification	Resulting URL	Next Step
1	Client sends request	/old-path	None	/old-path	Middleware intercepts
2	Middleware clones URL	/old-path	Clone URL object	/old-path	Modify URL
3	Middleware modifies pathname	/old-path	Change pathname to '/new-path'	/new-path	Rewrite request
4	Middleware returns rewrite response	/old-path	Rewrite to '/new-path'	/new-path	Route handler processes
5	Route handler receives modified request	/new-path	None	/new-path	Send response
6	Response sent to client	/new-path	None	/new-path	End

💡 Request is rewritten to '/new-path' and processed by route handler before response is sent.

Variable Tracker

Variable	Start	After Step 2	After Step 3	Final
request.nextUrl.pathname	/old-path	/old-path	/old-path	/new-path
url	undefined	URL object (clone)	URL object (modified)	URL object (modified)

Key Moments - 2 Insights

Why do we clone the URL before modifying it?

Cloning the URL creates a new object to safely modify without changing the original request URL directly, as shown in step 2 and 3 of the execution_table.

What happens if we don't return a NextResponse in middleware?

If middleware does not return a NextResponse, the request continues unchanged. The execution_table shows that returning NextResponse.rewrite triggers the URL change.

Visual Quiz - 3 Questions

Look at the execution_table, what is the request URL after step 3?

A /rewrite-path

B /old-path

C /new-path

D /modified-path

💡 Hint

Check the 'Resulting URL' column at step 3 in the execution_table.

At which step does the middleware send the modified request to the route handler?

A Step 4

B Step 2

C Step 5

D Step 6

💡 Hint

Look for when NextResponse.rewrite is returned in the execution_table.

If we skip cloning the URL and modify request.nextUrl.pathname directly, what changes in variable_tracker?

A url variable would be undefined

B request.nextUrl.pathname changes immediately without clone

C No change in variables

D Middleware fails to run

💡 Hint

Refer to variable_tracker showing cloning before modification.

Concept Snapshot

Next.js middleware can intercept requests to modify them.
Clone the request URL to safely change parts like pathname.
Return NextResponse.rewrite() with the new URL to forward modified request.
Route handler then processes the updated request.
This allows URL rewriting, header changes, or redirects before response.

Full Transcript

In Next.js, middleware runs before route handlers and can modify incoming requests. The middleware clones the request URL to avoid changing the original directly. It then modifies the clone, for example changing the pathname. Returning NextResponse.rewrite with the modified URL tells Next.js to process the request as if it was for the new URL. The route handler receives this modified request and sends back a response. This flow lets developers change request details like URL paths or headers before the main app logic runs.

Practice

1. In Next.js, what is the main purpose of modifying a request in middleware?

easy

A. To change request details like headers or body before the app processes it

B. To directly send a response to the client without processing

C. To update the database with request data

D. To log request details only without changing anything

Solution

1. Step 1: Understand middleware role in Next.js

   Middleware runs before the app processes a request, allowing changes to the request.

2. Step 2: Identify what request modification means

   Modifying means changing headers, body, or other request parts before the app sees it.

3. Final Answer:

   To change request details like headers or body before the app processes it -> Option A

4. Quick Check:

   Request modification = change request details [OK]

Hint: Middleware changes requests before app sees them [OK]

Common Mistakes:

• Confusing request modification with sending responses
• Thinking middleware updates databases directly
• Assuming middleware only logs requests

2. Which of the following is the correct way to return a modified request in Next.js middleware?

easy

A. return NextResponse.next(request);

B. return NextResponse.next(new Request(request));

C. return NextResponse.redirect('/new-path');

D. return NextResponse.next(new Request(request, { headers: { 'x-new': 'value' } }));

Solution

1. Step 1: Understand how to modify requests in Next.js middleware

   You must create a new Request object with changes (like new headers) and pass it to NextResponse.next().

2. Step 2: Check each option

   return NextResponse.next(request); passes original request without changes. return NextResponse.next(new Request(request)); creates a new Request but without changes. return NextResponse.next(new Request(request, { headers: { 'x-new': 'value' } })); creates a new Request with modified headers correctly. return NextResponse.redirect('/new-path'); redirects instead of modifying request.

3. Final Answer:

   return NextResponse.next(new Request(request, { headers: { 'x-new': 'value' } })); -> Option D

4. Quick Check:

   New Request with changes + NextResponse.next() = D [OK]

Hint: Wrap new Request with changes inside NextResponse.next() [OK]

Common Mistakes:

• Returning original request without changes
• Using redirect instead of next() for modification
• Not creating a new Request object for changes

3. Given this middleware code snippet, what will be the value of the header 'x-user' in the request seen by the app?

import { NextResponse } from 'next/server';
export function middleware(request) {
  const newHeaders = new Headers(request.headers);
  newHeaders.set('x-user', 'alice');
  const newRequest = new Request(request.url, { headers: newHeaders });
  return NextResponse.next(newRequest);
}

medium

A. null

B. undefined

C. alice

D. original header value if any

Solution

1. Step 1: Analyze header modification in middleware

   The code creates new headers from the original, sets 'x-user' to 'alice', then creates a new Request with these headers.

2. Step 2: Determine header value passed to app

   The app receives the new Request with 'x-user' header set to 'alice', so the value is 'alice'.

3. Final Answer:

   alice -> Option C

4. Quick Check:

   Header 'x-user' set to 'alice' in new Request [OK]

Hint: Headers set in new Request appear in app request [OK]

Common Mistakes:

• Assuming original headers remain unchanged
• Thinking header is removed or null
• Confusing middleware response headers with request headers

4. Identify the error in this Next.js middleware code that tries to add a custom header:

import { NextResponse } from 'next/server';
export function middleware(request) {
  request.headers.set('x-custom', '123');
  return NextResponse.next(request);
}

medium

A. Headers are immutable; cannot modify request.headers directly

B. NextResponse.next() cannot accept a Request object

C. Missing await keyword for asynchronous header setting

D. Middleware must return a Response, not NextResponse

Solution

1. Step 1: Check how headers can be modified in Next.js middleware

   Request headers are immutable; you cannot change them directly on the original request object.

2. Step 2: Identify correct way to modify headers

   You must create a new Headers object, modify it, then create a new Request with those headers.

3. Final Answer:

   Headers are immutable; cannot modify request.headers directly -> Option A

4. Quick Check:

   Request.headers immutable = B [OK]

Hint: Request.headers are read-only; create new Headers to modify [OK]

Common Mistakes:

• Trying to set headers directly on request.headers
• Assuming NextResponse.next() rejects Request objects
• Confusing async code requirement for headers

5. You want to add a custom header 'x-trace-id' with a unique value to every request in Next.js middleware, but only if the header is not already present. Which code snippet correctly implements this?

hard

A. import { NextResponse } from 'next/server';
export function middleware(request) {
const headers = request.headers;
if (!headers.has('x-trace-id')) {
headers.set('x-trace-id', crypto.randomUUID());
}
return NextResponse.next(request);
}

B. import { NextResponse } from 'next/server';
export function middleware(request) {
if (!request.headers.has('x-trace-id')) {
const headers = new Headers(request.headers);
headers.set('x-trace-id', crypto.randomUUID());
const newRequest = new Request(request.url, { headers });
return NextResponse.next(newRequest);
}
return NextResponse.next();
}

C. import { NextResponse } from 'next/server';
export function middleware(request) {
const newRequest = new Request(request.url, { headers: { 'x-trace-id': crypto.randomUUID() } });
return NextResponse.next(newRequest);
}

D. import { NextResponse } from 'next/server';
export function middleware(request) {
const headers = new Headers();
headers.set('x-trace-id', crypto.randomUUID());
const newRequest = new Request(request.url, { headers });
return NextResponse.next(newRequest);
}

Solution

1. Step 1: Identify the correct conditional logic and immutable handling

   Check !request.headers.has('x-trace-id'), then const headers = new Headers(request.headers); headers.set('x-trace-id', crypto.randomUUID()); const newRequest = new Request(request.url, { headers }); return NextResponse.next(newRequest); else return NextResponse.next().

2. Step 2: Why it works

   Clones headers immutably, adds conditionally if missing, preserves other headers, forwards new request or original.

3. Step 3: Why others fail

   Direct set on request.headers throws immutable error. new Request with { headers: { 'x-trace-id': ... } } replaces all headers. new Headers() starts empty, loses original headers.

4. Final Answer:

   import { NextResponse } from 'next/server'; export function middleware(request) { if (!request.headers.has('x-trace-id')) { const headers = new Headers(request.headers); headers.set('x-trace-id', crypto.randomUUID()); const newRequest = new Request(request.url, { headers }); return NextResponse.next(newRequest); } return NextResponse.next(); } -> Option B

5. Quick Check:

   Check header, clone headers, set new, return new Request = A [OK]

Hint: Clone headers, check presence, set if missing, return new Request [OK]

Common Mistakes:

• Modifying request.headers directly
• Overwriting all headers instead of cloning
• Not checking if header already exists