Read or modify request cookies
A Route Handler needs to inspect a session, preference, or feature cookie before producing a response.
Next.js 16+ · Class
NextRequest
NextRequest extends the Web Request API with Next.js conveniences for incoming requests. Its cookies API handles request cookies, while nextUrl provides an extended parsed URL.
How it works
NextRequest is Next.js's extension of the Web Request API for incoming requests. It preserves standard Request capabilities while adding request-cookie access and nextUrl, which extends URL with Next.js-specific properties and convenient parsed URL handling.
Syntax
import type { NextRequest } from 'next/server'Parameters
| Name | Type | Description |
|---|---|---|
request | NextRequest | Incoming HTTP request represented by the NextRequest instance. |
Returns
No class return value; NextRequest is an object representing an incoming HTTP request.
Key points
- Use NextRequest as a request object with the standard Web Request interface plus Next.js conveniences.
- The cookies API supports request-cookie access and mutation through the cookies property.
- cookies.get(name) retrieves a cookie value by name.
- nextUrl builds on URL and adds Next.js-specific URL capabilities.
- The extended URL object exposes properties beyond those available on the native URL API.
Common mistakes
- A cookie lookup can produce undefined when the requested cookie is absent; handle the optional result before reading its value.
- Do not rely on ip or geo properties in the current API; the documentation records their removal in v15.0.0.
Example: Read request cookies and query parameters
import type { NextRequest } from 'next/server'
export function GET(request: NextRequest) {
const theme = request.cookies.get('theme')?.value
const category = request.nextUrl.searchParams.get('category')
return Response.json({ theme, category })
}A Route Handler can use NextRequest to read a cookie and a parsed query parameter before returning a Web Response.
When to use it
Inspect the parsed request URL
A handler needs typed, convenient access to pathname and query-string data from the incoming URL.
Handle incoming Route Handler requests
A server-side request handler needs standard Request methods together with Next.js-specific request helpers.
Interview questions
QWhat is NextRequest?
NextRequest extends the standard Web Request API, so it can be used where normal request behavior is needed. It additionally provides cookies and nextUrl for Next.js-specific request handling.
Follow-up: How would you extract a query parameter? Use request.nextUrl.searchParams.get('name'), which applies the URL API's search-parameter interface.
QHow does NextRequest expose cookies?
The cookies property lets code read or mutate the request's Set-Cookie-related cookie data. Its get(name) operation returns the cookie value, returns undefined when absent, and returns the first matching value when multiple cookies exist.
Follow-up: How should absent cookies be handled? Treat the result as optional and branch or use optional chaining before accessing the value.
QWhat does nextUrl provide?
nextUrl extends the native URL API with additional convenience methods and Next.js-specific properties. It is useful for inspecting the parsed incoming URL, including query parameters through searchParams.
Follow-up: What should replace removed request metadata? Do not use ip or geo from the current NextRequest API; obtain deployment-specific information through supported platform mechanisms instead.
Related
RequestURLcookiesnextUrlRoute HandlersNextResponse