149 lines
3.3 KiB
Markdown
149 lines
3.3 KiB
Markdown
---
|
||
description: Add custom HTTP headers to your Next.js app.
|
||
---
|
||
|
||
# Headers
|
||
|
||
> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
|
||
|
||
Headers allow you to set custom HTTP headers for an incoming request path.
|
||
|
||
To set custom HTTP headers you can use the `headers` key in `next.config.js`:
|
||
|
||
```js
|
||
module.exports = {
|
||
async headers() {
|
||
return [
|
||
{
|
||
source: '/about',
|
||
headers: [
|
||
{
|
||
key: 'x-custom-header',
|
||
value: 'my custom header value',
|
||
},
|
||
{
|
||
key: 'x-another-custom-header',
|
||
value: 'my other custom header value',
|
||
},
|
||
],
|
||
},
|
||
,
|
||
]
|
||
},
|
||
}
|
||
```
|
||
|
||
`headers` is an async function that expects an array to be returned holding objects with `source` and `headers` properties:
|
||
|
||
- `source` is the incoming request path pattern.
|
||
- `headers` is an array of header objects with the `key` and `value` properties.
|
||
|
||
## Path Matching
|
||
|
||
Path matches are allowed, for example `/blog/:slug` will match `/blog/hello-world` (no nested paths):
|
||
|
||
```js
|
||
module.exports = {
|
||
async headers() {
|
||
return [
|
||
{
|
||
source: '/blog/:slug',
|
||
headers: [
|
||
{
|
||
key: 'x-slug',
|
||
value: ':slug', // Matched parameters can be used in the value
|
||
},
|
||
{
|
||
key: 'x-slug-:slug', // Matched parameters can be used in the key
|
||
value: 'my other custom header value',
|
||
},
|
||
],
|
||
},
|
||
,
|
||
]
|
||
},
|
||
}
|
||
```
|
||
|
||
### Wildcard Path Matching
|
||
|
||
To match a wildcard path you can use `*` after a parameter, for example `/blog/:slug*` will match `/blog/a/b/c/d/hello-world`:
|
||
|
||
```js
|
||
module.exports = {
|
||
async headers() {
|
||
return [
|
||
{
|
||
source: '/blog/:slug*',
|
||
headers: [
|
||
{
|
||
key: 'x-slug',
|
||
value: ':slug*', // Matched parameters can be used in the value
|
||
},
|
||
{
|
||
key: 'x-slug-:slug*', // Matched parameters can be used in the key
|
||
value: 'my other custom header value',
|
||
},
|
||
],
|
||
},
|
||
,
|
||
]
|
||
},
|
||
}
|
||
```
|
||
|
||
### Regex Path Matching
|
||
|
||
To match a regex path you can wrap the regex in parenthesis after a parameter, for example `/blog/:slug(\\d{1,})` will match `/blog/123` but not `/blog/abc`:
|
||
|
||
```js
|
||
module.exports = {
|
||
async rewrites() {
|
||
return [
|
||
{
|
||
source: '/blog/:post(\\d{1,})',
|
||
headers: [
|
||
{
|
||
key: 'x-post',
|
||
value: ':post',
|
||
},
|
||
],
|
||
},
|
||
]
|
||
},
|
||
}
|
||
```
|
||
|
||
### Headers with basePath support
|
||
|
||
When leveraging [`basePath` support](/docs/api-reference/next.config.js/basepath.md) with headers each `source` is automatically prefixed with the `basePath` unless you add `basePath: false` to the header:
|
||
|
||
```js
|
||
module.exports = {
|
||
basePath: '/docs',
|
||
|
||
async headers() {
|
||
return [
|
||
{
|
||
source: '/with-basePath', // becomes /docs/with-basePath
|
||
headers: [
|
||
{
|
||
key: 'x-hello',
|
||
value: 'world'
|
||
}
|
||
]
|
||
},
|
||
{
|
||
source: '/without-basePath', // is not modified since basePath: false is set
|
||
headers: [
|
||
{
|
||
key: 'x-hello',
|
||
value: 'world'
|
||
}
|
||
]
|
||
basePath: false
|
||
},
|
||
]
|
||
},
|
||
}
|
||
```
|