mirror of
https://github.com/vercel/next.js.git
synced 2026-09-20 02:25:18 +08:00
Joseph
0553b34542
- changes getting started -> caching - new guide for instant navs - new guide for runtime-prefetching (most pending stuff is here) - x-refs between docs - App Shell mentions in other docs (ISR w/ CC) --------- Co-authored-by: Aurora Scharff <66901228+aurorascharff@users.noreply.github.com> Co-authored-by: Aurora Scharff <aurora.sofie@gmail.com>
75 lines
4.1 KiB
Plaintext
75 lines
4.1 KiB
Plaintext
---
|
|
title: headers
|
|
description: API reference for the headers function.
|
|
---
|
|
|
|
`headers` is an **async** function that allows you to **read** the HTTP incoming request headers from a [Server Component](/docs/app/getting-started/server-and-client-components).
|
|
|
|
```tsx filename="app/page.tsx" switcher
|
|
import { headers } from 'next/headers'
|
|
|
|
export default async function Page() {
|
|
const headersList = await headers()
|
|
const userAgent = headersList.get('user-agent')
|
|
}
|
|
```
|
|
|
|
```jsx filename="app/page.js" switcher
|
|
import { headers } from 'next/headers'
|
|
|
|
export default async function Page() {
|
|
const headersList = await headers()
|
|
const userAgent = headersList.get('user-agent')
|
|
}
|
|
```
|
|
|
|
## Reference
|
|
|
|
### Parameters
|
|
|
|
`headers` does not take any parameters.
|
|
|
|
### Returns
|
|
|
|
`headers` returns a **read-only** [Web Headers](https://developer.mozilla.org/docs/Web/API/Headers) object.
|
|
|
|
- [`Headers.entries()`](https://developer.mozilla.org/docs/Web/API/Headers/entries): Returns an [`iterator`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols) allowing to go through all key/value pairs contained in this object.
|
|
- [`Headers.forEach()`](https://developer.mozilla.org/docs/Web/API/Headers/forEach): Executes a provided function once for each key/value pair in this `Headers` object.
|
|
- [`Headers.get()`](https://developer.mozilla.org/docs/Web/API/Headers/get): Returns a [`String`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) sequence of all the values of a header within a `Headers` object with a given name.
|
|
- [`Headers.has()`](https://developer.mozilla.org/docs/Web/API/Headers/has): Returns a boolean stating whether a `Headers` object contains a certain header.
|
|
- [`Headers.keys()`](https://developer.mozilla.org/docs/Web/API/Headers/keys): Returns an [`iterator`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols) allowing you to go through all keys of the key/value pairs contained in this object.
|
|
- [`Headers.values()`](https://developer.mozilla.org/docs/Web/API/Headers/values): Returns an [`iterator`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols) allowing you to go through all values of the key/value pairs contained in this object.
|
|
|
|
## Good to know
|
|
|
|
- `headers` is an **asynchronous** function that returns a promise. You must use `async/await` or React's [`use`](https://react.dev/reference/react/use) function.
|
|
- In version 14 and earlier, `headers` was a synchronous function. To help with backwards compatibility, you can still access it synchronously in Next.js 15, but this behavior will be deprecated in the future.
|
|
- Since `headers` is read-only, you cannot `set` or `delete` the outgoing request headers.
|
|
- `headers` is a [Request-time API](/docs/app/glossary#request-time-apis) whose returned values cannot be known ahead of time. Using it in will opt a route into **[dynamic rendering](/docs/app/glossary#dynamic-rendering)**.
|
|
- With [Cache Components](/docs/app/getting-started/caching), calling `headers()` outside of a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary prevents the route from being prerendered. See [Next.js encountered runtime data during prerendering](/docs/messages/blocking-prerender-runtime) for fix options.
|
|
|
|
## Examples
|
|
|
|
### Using the Authorization header
|
|
|
|
```jsx filename="app/page.js"
|
|
import { headers } from 'next/headers'
|
|
|
|
export default async function Page() {
|
|
const authorization = (await headers()).get('authorization')
|
|
const res = await fetch('...', {
|
|
headers: { authorization }, // Forward the authorization header
|
|
})
|
|
const user = await res.json()
|
|
|
|
return <h1>{user.name}</h1>
|
|
}
|
|
```
|
|
|
|
## Version History
|
|
|
|
| Version | Changes |
|
|
| ------------ | ------------------------------------------------------------------------------------------------------ |
|
|
| `v15.0.0-RC` | `headers` is now an async function. A [codemod](/docs/app/guides/upgrading/codemods#150) is available. |
|
|
| `v13.0.0` | `headers` introduced. |
|