Skip to content

Commit

Permalink
Improve rewrites documentation (#34725)
Browse files Browse the repository at this point in the history
This is a PR to update the rewrites documentation. This is after struggling to get rewrites to work with `trailingSlash` for a customer as this wasn't documented. The main culprit was the `:path*` wildcard not catching trailing slashes. The changes made to for this commit were:

- [x] Added example for redirecting to blog and docs
- [x] Expanded on original code example for external URLs
- [x] Added code example for using rewrites with `trailingSlash`

### Context

For a reproduction of the `:path*` wildcard not catching trailing slashes as expected, see below. Click on the "not working" demo link below, navigate to a specific blog post, then reload the page. It will redirect infinitely.

- [Not working demo of main repo with `:path*`](https://redirect-demo-git-not-working-nutlope.vercel.app/blog/)
- [Working demo of main repo with `:path(.+)`](https://redirect-demo.vercel.app/blog/)

If you want to take a look at the code, here are the full repos. They both have `trailingSlash: true`:

- [not working main repo](https://github.com/Nutlope/redirect-demo/tree/not-working) 
- [working main repo](https://github.com/Nutlope/redirect-demo)
- [blog repo](https://github.com/Nutlope/starter-blog-example)
  • Loading branch information
Nutlope committed Feb 24, 2022
1 parent ceecf91 commit ae2d901
Showing 1 changed file with 26 additions and 1 deletion.
27 changes: 26 additions & 1 deletion docs/api-reference/next.config.js/rewrites.md
Expand Up @@ -300,15 +300,20 @@ module.exports = {
<summary><b>Examples</b></summary>
<ul>
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/custom-routes-proxying">Incremental adoption of Next.js</a></li>
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-zones">Using Multiple Zones</a></li>
</ul>
</details>

Rewrites allow you to rewrite to an external url. This is especially useful for incrementally adopting Next.js.
Rewrites allow you to rewrite to an external url. This is especially useful for incrementally adopting Next.js. The following is an example rewrite for redirecting the `/blog` route of your main app to an external site.

```js
module.exports = {
async rewrites() {
return [
{
source: '/blog',
destination: 'https://example.com/blog',
},
{
source: '/blog/:slug',
destination: 'https://example.com/blog/:slug', // Matched parameters can be used in the destination
Expand All @@ -318,6 +323,26 @@ module.exports = {
}
```

If you're using `trailingSlash: true`, you also need to insert a trailing slash in the `source` paramater. If the destination server is also expecting a trailing slash it should be included in the `destination` parameter as well.

```js
module.exports = {
trailingSlash: 'true',
async rewrites() {
return [
{
source: '/blog/',
destination: 'https://example.com/blog/',
},
{
source: '/blog/:path*/',
destination: 'https://example.com/blog/:path*/',
},
]
},
}
```

### Incremental adoption of Next.js

You can also have Next.js fall back to proxying to an existing website after checking all Next.js routes.
Expand Down

0 comments on commit ae2d901

Please sign in to comment.