766fef2271
This adds an example of using regex matching for custom routes Fixes https://github.com/vercel/next.js/issues/15712
147 lines
3.2 KiB
Markdown
147 lines
3.2 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',
|
|
},
|
|
],
|
|
},
|
|
,
|
|
]
|
|
},
|
|
}
|
|
```
|
|
|
|
### 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
|
|
},
|
|
]
|
|
},
|
|
}
|
|
```
|