JSON endpoints
A Route Handler needs a structured HTTP payload for a browser or API client.
Next.js 16+ · Class
NextResponse
NextResponse extends the Web Response API with convenient helpers for JSON responses, redirects, rewrites, continued Proxy routing, and response cookies. It can be returned from Route Handlers or Proxy wherever a standard Response is accepted.
How it works
NextResponse extends the Web Response API with helpers for common App Router response tasks. In Route Handlers and Proxy, it can produce JSON, redirect or rewrite requests, continue routing, and manipulate response cookies; the returned object can be used anywhere a standard Response is expected.
Syntax
import { NextResponse } from 'next/server'Returns
A NextResponse instance, which can be returned wherever a standard Web Response is expected.
Key points
- NextResponse preserves the standard Response model while adding Next.js-specific response helpers.
- Use NextResponse.json when an endpoint needs to return structured JSON.
- NextResponse.redirect sends the client toward another URL rather than serving the current route’s content.
- The response cookies interface supports reading existing cookies and setting or changing cookie values.
- cookies.set(name, value) attaches a named cookie value to the outgoing response.
- In Proxy, NextResponse.next lets processing continue without immediately replacing the request with a new destination.
Common mistakes
- Use next() to continue routing from Proxy; it is not a replacement for producing a response in every context.
- cookies.get(name) returns only the first matching cookie when multiple cookies share the name.
Example: Return JSON from a Route Handler
import { NextResponse } from 'next/server'
export function GET() {
return NextResponse.json({ ok: true })
}A Route Handler can return a JSON response created by NextResponse.json.
When to use it
Route rewrites
A request should be served by another route without exposing that internal destination in the browser URL.
Redirects
An authentication or locale check must send the client to a different destination.
Response cookies
A response must establish or update session, preference, or tracking state.
Interview questions
QWhat is NextResponse, and how does it relate to Response?
NextResponse is Next.js’s extension of the Web Response API. It adds helpers such as json(), redirect(), rewrite(), next(), and response-cookie operations, while remaining returnable wherever a Response is accepted.
Follow-up: How would you expose a modified request header upstream? Use NextResponse.next with an options object whose request property contains the new headers; putting headers at the top level sends response headers to the client.
QHow do you return JSON from an App Router Route Handler?
NextResponse.json creates a response whose body contains the supplied JSON value. A Route Handler can return that result directly, for example from a GET function.
Follow-up: When would rewrite be preferable to redirect? Rewrite serves another route while keeping the requested URL, whereas redirect instructs the client to navigate to a different URL.
QHow does NextResponse handle response cookies?
The cookies API reads or mutates the response’s Set-Cookie header. set(name, value) adds a cookie, get(name) reads one, and has(name) checks whether one exists.
Follow-up: What should code account for when reading cookies? get can return undefined when no cookie is found, and with duplicate names it returns the first match.
Related
NextRequestRoute HandlersProxyResponsecookiesjson()redirect()rewrite()