3a9cb2c5b3
Follow-up to https://github.com/vercel/next.js/pull/15041 this updates the documentation for custom-routes to mention `basePath` handling with them
125 lines
2.7 KiB
Markdown
125 lines
2.7 KiB
Markdown
---
|
|
description: Add custom HTTP headers to your Next.js app.
|
|
---
|
|
|
|
# Headers
|
|
|
|
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',
|
|
},
|
|
],
|
|
},
|
|
,
|
|
]
|
|
},
|
|
}
|
|
```
|
|
|
|
### 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
|
|
},
|
|
]
|
|
},
|
|
}
|
|
```
|