Next.js 16+ · Module

next/headers

next/headers provides the asynchronous headers function for reading incoming request headers. It returns a read-only Web Headers object and uses request-time data, so calling it opts the route into dynamic rendering.

Since: v15.0.0-RC

How it works

Import the asynchronous headers function from next/headers and await it in a Server Component, Route Handler, or Server Action. The resulting read-only Web Headers object supports standard methods such as get; because the values are request-specific, using it makes the route dynamically rendered.

Syntax

import { headers } from 'next/headers'
const headersList = await headers()

Returns

A Promise that resolves to a read-only Web Headers object.

Key points

Use it to inspect headers arriving with the current HTTP request.
The result follows the Web Headers interface and exposes read operations.
Invoke the function without arguments.
A route that reads request headers is evaluated at request time.

Common mistakes

Reading request headers makes the route request-time and prevents it from being fully statically rendered.
Do not call headers synchronously in current Next.js; await it or consume its promise with React's use.

Example: Read an incoming header

import { headers } from 'next/headers'

export default async function Page() {
  const requestHeaders = await headers()
  const userAgent = requestHeaders.get('user-agent')

  return <p>User agent: {userAgent ?? 'unknown'}</p>
}

Reads the incoming User-Agent header in a Server Component and renders it.

When to use it

Read client metadata

A Server Component needs to personalize output from the browser or proxy request.

Inspect request context

A Route Handler needs to inspect authorization or forwarding information before producing a response.

Use Web Headers methods

A server-side operation needs request-specific values while retaining the standard Web Headers API.

Interview questions

QWhat does next/headers provide?

headers is an asynchronous function from next/headers that reads incoming HTTP request headers. It returns a read-only Web Headers object, so standard methods such as get can inspect values but cannot mutate outgoing headers.

Follow-up: How would you send a response header instead? Return a Response, or another response object, constructed with the desired headers rather than modifying the value returned by headers().

QHow do you read a request header?

Call await headers() inside an async Server Component, Route Handler, or Server Action, then use methods such as get. The function takes no parameters.

Follow-up: Why can this affect caching? Its values are unavailable before the request, so using it opts the route into dynamic rendering.

QWhy does using headers affect rendering?

The API is request-time because incoming header values cannot be known ahead of the request. Consequently, a route that uses it is rendered dynamically rather than being treated as fully static.

Follow-up: Can the returned object set a cookie or response header? No; it is read-only, so response metadata must be set on the returned response.

cookies
draftMode
Route Handlers
Server Components
Request-time APIs

Source: Functions: headers. Checked 2026-10-15.