Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update headers API reference to reflect async Dynamic APIs breaking change #70950

Closed
wants to merge 1 commit into from
Closed

docs: update headers API reference to reflect async Dynamic APIs breaking change #70950

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 39 additions & 10 deletions docs/02-app/02-api-reference/04-functions/headers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,41 @@ This API extends the [Web Headers API](https://developer.mozilla.org/docs/Web/AP
```tsx filename="app/page.tsx" switcher
import { headers } from 'next/headers'

// Async page component
export default async function Page() {
const headersList = await headers()
const referer = headersList.get('referer')

return <div>Referer: {referer}</div>
}

// Sync page component
import { use } from "react"

export default function Page() {
const headersList = headers()
const headersList = use(headers())
const referer = headersList.get('referer')

return <div>Referer: {referer}</div>
}
```

```jsx filename="app/page.js" switcher
```jsx filename="app/page.jsx" switcher
import { headers } from 'next/headers'

// Async page component
export default async function Page() {
const headersList = await headers()
const referer = headersList.get('referer')

return <div>Referer: {referer}</div>
}

// Sync page component
import { use } from "react"

export default function Page() {
const headersList = headers()
const headersList = use(headers())
const referer = headersList.get('referer')

return <div>Referer: {referer}</div>
Expand All @@ -33,12 +55,18 @@ export default function Page() {

> **Good to know**:
>
> - `headers()` is a **[Dynamic Function](/docs/app/building-your-application/rendering/server-components#server-rendering-strategies#dynamic-functions)** whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into **[dynamic rendering](/docs/app/building-your-application/rendering/server-components#dynamic-rendering)** at request time.
> - `headers()` is an async **[Dynamic Function](/docs/app/building-your-application/rendering/server-components#server-rendering-strategies#dynamic-functions)** whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into **[dynamic rendering](/docs/app/building-your-application/rendering/server-components#dynamic-rendering)** at request time.

### API Reference

```tsx
const headersList = headers()
// async server component
const headersList = await headers()

// sync server component
import { use } from "react"

const headersList = use(headers())
```

#### Parameters
Expand All @@ -47,7 +75,7 @@ const headersList = headers()

#### Returns

`headers` returns a **read-only** [Web Headers](https://developer.mozilla.org/docs/Web/API/Headers) object.
`headers` returns a promise **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.
Expand All @@ -67,7 +95,7 @@ import { Suspense } from 'react'
import { headers } from 'next/headers'

async function User() {
const authorization = headers().get('authorization')
const authorization = (await headers()).get('authorization')
const res = await fetch('...', {
headers: { authorization }, // Forward the authorization header
})
Expand All @@ -93,15 +121,15 @@ export default function Page() {
import { Suspense } from 'react'
import { headers } from 'next/headers'

function IP() {
async function IP() {
const FALLBACK_IP_ADDRESS = '0.0.0.0'
const forwardedFor = headers().get('x-forwarded-for')
const forwardedFor = (await headers()).get('x-forwarded-for')

if (forwardedFor) {
return forwardedFor.split(',')[0] ?? FALLBACK_IP_ADDRESS
}

return headers().get('x-real-ip') ?? FALLBACK_IP_ADDRESS
return (await headers()).get('x-real-ip') ?? FALLBACK_IP_ADDRESS
}

export default function Page() {
Expand All @@ -125,3 +153,4 @@ In addition to `x-forwarded-for`, `headers()` can also read:
| Version | Changes |
| --------- | --------------------- |
| `v13.0.0` | `headers` introduced. |
| `v15.0.0` | `headers` returns a promise |
Loading