`NextRequest` and `NextResponse` Explained

NextRequest and NextResponse are Next.js wrappers around the standard Web Request and Response APIs. NextRequest adds cookie helpers and a parsed nextUrl, while NextResponse adds json, redirect, rewrite, and cookie helpers.

You do not need them for every handler. Plain Request and Response cover most cases, and these wrappers add convenience only when you need their extras.

Both come from next/server, and importing the NextRequest type is enough to get the extended fields in TypeScript. Here is NextRequest reading a query value.

typescript

// app/api/search/route.ts
import { type NextRequest } from 'next/server'
 
export async function GET(request: NextRequest) {
  const q = request.nextUrl.searchParams.get('q')
  return Response.json({ q })
}

The handler reads the q query param through nextUrl and returns it. The plain Request object has no nextUrl, so the wrapper is what provides the parsed URL.

What NextRequest adds

NextRequest extends the Web Request API with two main additions: cookies and nextUrl. The cookies object reads and mutates request cookies, and nextUrl is a URL extended with Next.js specific fields.

The useful nextUrl fields are pathname and searchParams, which behave like the standard URL API. It also exposes basePath and buildId for framework metadata. The ip and geo properties were removed in Next.js 15, so do not depend on them.

The cookies object exposes get, getAll, has, set, and delete, which work with cookies on the request without parsing headers by hand. Mutating request cookies does not send a cookie to the browser. To do that, set the cookie on the response.

What NextResponse adds

NextResponse extends the Web Response API with response helpers. Some apply in Route Handlers, while rewrite and next belong to Proxy routing control.

The redirect helper returns a response that moves the client to a new URL, preserving the current host when you build the target from request.url. The rewrite and next helpers control routing from proxy.ts, where the exported function is named proxy in Next.js 16.

typescript

// app/api/welcome/route.ts
import { NextResponse } from 'next/server'
 
export async function GET() {
  const response = NextResponse.json({ message: 'Welcome back' })
  response.cookies.set('visited', 'true', {
    httpOnly: true,
    sameSite: 'lax',
  })
  return response
}

This returns JSON and sends a visited cookie on the same response. Setting cookies on a plain Response requires building the Set-Cookie header yourself, so the helper avoids manual header formatting.

Read and set cookies

Reading cookies from the request and setting them on the response are the two most common cookie tasks. Use request.cookies.get on NextRequest to read and response.cookies.set on NextResponse to write.

The response cookie helper builds the Set-Cookie header for you. Changing request.cookies only changes the request-side cookie representation, so it is not a substitute for returning a response cookie.

When to use each

Use plain Request and Response for simple handlers. Reach for NextRequest when you need cookies or nextUrl, and NextResponse in a Route Handler when you need response cookie or redirect helpers. Use rewrite and next from Proxy, not as general Route Handler flow control.

For a handler that only returns JSON, plain Response.json is enough and keeps imports small. Add the wrappers only when the extra helpers actually appear in your code.

Common mistakes

Treating nextUrl as a plain string is one mistake. It is a URL object, so access fields such as pathname and searchParams instead of concatenating strings.

Relying on ip or geo is another, because both were removed in Next.js 15. Use a trusted API supplied by your deployment provider when you need location or IP metadata.

Importing NextResponse just to return plain JSON is a third mistake, because Response.json already covers that case. Add the wrappers only for the helpers you actually call.

For redirects and streaming, see returning JSON, files, streams, and redirects. For reading input, see reading the request body, query params, and headers, and for the file convention, see Route Handlers in Next.js.