NextRequest

API reference for the NextRequest class, which extends the Web Request API with additional helpers for Next.js middleware and Route Handlers.

NextRequest extends the native Web Request API with additional convenience methods for use in Middleware and Route Handlers.

middleware.ts

import { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const token = request.cookies.get('auth-token')
  // ...
}

cookies

Read or mutate the cookies on the incoming request.

get(name) · { name: string; value: string } | undefined

Returns the first cookie with the given name, or undefined if not found.

// { name: 'show-banner', value: 'false', Path: '/home' }
request.cookies.get('show-banner')

getAll(name?) · { name: string; value: string }[]

Returns all cookies with the given name, or all cookies if no name is provided.

request.cookies.getAll('experiments')
request.cookies.getAll() // all cookies

set(name, value) · void

Sets a cookie on the request.

request.cookies.set('show-banner', 'false')

delete(name) · boolean

Deletes the cookie with the given name. Returns true if deleted, false otherwise.

request.cookies.delete('experiments')

has(name) · boolean

Returns true if the cookie exists.

request.cookies.has('experiments')

clear() · void

Removes all cookies from the request.

request.cookies.clear()

nextUrl

Extends the native URL API with Next.js-specific properties.

// Given a request to /home
request.nextUrl.pathname     // '/home'

// Given a request to /home?name=lee
request.nextUrl.searchParams // URLSearchParams { 'name' => 'lee' }

Available properties

Property	Type	Description
basePath	string	The base path of the URL.
buildId	string | undefined	The build identifier of the Next.js app. Can be customized.
pathname	string	The URL pathname.
searchParams	URLSearchParams	The URL search parameters.

The internationalization properties available in the Pages Router (locale, locales, defaultLocale, domainLocale) are not available in the App Router. Use the App Router internationalization guide instead.

Inherited from Request

NextRequest inherits all properties and methods from the native Request API, including:

• method — HTTP method (e.g. 'GET', 'POST')
• url — The full request URL as a string
• headers — A read-only Headers object
• body — The request body as a ReadableStream
• json(), text(), arrayBuffer(), formData() — Body parsing methods

Example

middleware.ts

import { NextRequest, NextResponse } from 'next/server'

export function middleware(request: NextRequest) {
  const country = request.headers.get('x-country')
  const isLoggedIn = request.cookies.has('session')

  if (!isLoggedIn && request.nextUrl.pathname.startsWith('/dashboard')) {
    const loginUrl = new URL('/login', request.url)
    loginUrl.searchParams.set('from', request.nextUrl.pathname)
    return NextResponse.redirect(loginUrl)
  }

  return NextResponse.next()
}

Version history

Version	Changes
v15.0.0	ip and geo properties removed.