From ae2d901eed3537e46a24e6e1963815230b92d6da Mon Sep 17 00:00:00 2001
From: Hassan El Mghari <he55@drexel.edu>
Date: Thu, 24 Feb 2022 17:25:56 -0500
Subject: [PATCH] Improve rewrites documentation (#34725)

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)
---
 docs/api-reference/next.config.js/rewrites.md | 27 ++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/api-reference/next.config.js/rewrites.md b/docs/api-reference/next.config.js/rewrites.md
index 16ae2b533df8..47571668dfb2 100644
--- a/docs/api-reference/next.config.js/rewrites.md
+++ b/docs/api-reference/next.config.js/rewrites.md
@@ -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
@@ -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.