Example for Rewrites (Custom routes) (#15403)

This PR adds example for #15073  
> - [ ] `rewrites` For [docs/api-reference/next.config.js/rewrites.md](https://github.com/vercel/next.js/blob/canary/docs/api-reference/next.config.js/rewrites.md)

docs/api-reference/next.config.js/rewrites.md

@@ -4,6 +4,13 @@ description: Add rewrites to your Next.js app.
 
 # Rewrites
 
+<details>
+  <summary><b>Examples</b></summary>
+  <ul>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/rewrites">Rewrites</a></li>
+  </ul>
+</details>
+
 Rewrites allow you to map an incoming request path to a different destination path.
 
 Rewrites are only available on the Node.js environment and do not affect client-side routing.

examples/rewrites/.gitignore

+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# vercel
+.vercel

examples/rewrites/README.md

+# Rewrites Example
+
+This example shows how to use [rewrites in Next.js](https://nextjs.org/docs/api-reference/next.config.js/rewrites) to map an incoming request path to a different destination path.
+
+The index page ([`pages/index.js`](pages/index.js)) has a list of links that match the rewrites defined in [`next.config.js`](next.config.js). Run or deploy the app to see how it works!
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com):
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/import/project?template=https://github.com/vercel/next.js/tree/canary/examples/rewrites)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example:
+
+```bash
+npx create-next-app --example rewrites rewrites-app
+# or
+yarn create next-app --example rewrites rewrites-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).

examples/rewrites/next.config.js

+module.exports = {
+  async rewrites() {
+    return [
+      {
+        source: '/team',
+        destination: '/about',
+      },
+      {
+        source: '/about-us',
+        destination: '/about',
+      },
+      // Path Matching - will match `/post/a` but not `/post/a/b`
+      {
+        source: '/post/:slug',
+        destination: '/news/:slug',
+      },
+      // Wildcard Path Matching - will match `/news/a` and `/news/a/b`
+      {
+        source: '/blog/:slug*',
+        destination: '/news/:slug*',
+      },
+      // Rewriting to an external URL
+      {
+        source: '/docs/:slug',
+        destination: 'http://example.com/docs/:slug',
+      },
+    ]
+  },
+}

examples/rewrites/package.json

+{
+  "name": "rewrites",
+  "version": "1.0.0",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "next": "9.4.5-canary.43",
+    "react": "^16.13.1",
+    "react-dom": "^16.13.1"
+  },
+  "license": "MIT"
+}

examples/rewrites/pages/about.js

+import { useState, useEffect } from 'react'
+import { useRouter } from 'next/router'
+import Link from 'next/link'
+import styles from '../styles.module.css'
+
+const Code = (p) => <code className={styles.inlineCode} {...p} />
+
+export default function About() {
+  const { asPath, route } = useRouter()
+  const [path, setPath] = useState()
+
+  // `asPath` is always `/about` in Node.js (server render), because the page is statically generated
+  // so we wait for the browser to load, and use the updated `asPath`, which may be a path
+  // other than `/about` when using a rewrite. This way we can avoid a content mismatch
+  useEffect(() => setPath(asPath), [asPath])
+
+  return (
+    <div className={styles.container}>
+      <div className={styles.card}>
+        <h1>Path: {path}</h1>
+        <hr className={styles.hr} />
+        <p>
+          {' '}
+          This page was rendered by <Code>{`pages${route}.js`}</Code>.
+        </p>
+        <Link href="/">
+          <a> &larr; Back home</a>
+        </Link>
+      </div>
+    </div>
+  )
+}

examples/rewrites/pages/index.js

+import styles from '../styles.module.css'
+import Link from 'next/link'
+
+const Code = (p) => <code className={styles.inlineCode} {...p} />
+
+const Index = () => (
+  <div className={styles.container}>
+    <div className={styles.card}>
+      <h1>Rewrites with Next.js</h1>
+      <hr className={styles.hr} />
+      <p>
+        The links below are{' '}
+        <a href="https://nextjs.org/docs/api-reference/next.config.js/rewrites">
+          custom <Code>rewrites</Code>
+        </a>{' '}
+        that map an incoming request path to a different destination path.
+      </p>
+      <nav>
+        <ul className={styles.list}>
+          <li>
+            <Link href="/about" as="/team">
+              <a>Visit /team</a>
+            </Link>
+          </li>
+          <li>
+            <Link href="/about" as="/about-us">
+              <a>Visit /about-us</a>
+            </Link>
+          </li>
+          <li>
+            <Link href="/post/first-post">
+              <a>Visit /post/first-post</a>
+            </Link>
+          </li>
+          <li>
+            <Link href="/blog/2020/first-post">
+              <a>Visit /blog/2020/first-post</a>
+            </Link>
+          </li>
+          <li>
+            <a href="/docs/page">Visit External URL</a>
+          </li>
+        </ul>
+      </nav>
+      <p>
+        Open <Code>next.config.js</Code> to learn more about the rewrites that
+        match the links above.
+      </p>
+      <hr className={styles.hr} />
+    </div>
+  </div>
+)
+
+export default Index

examples/rewrites/pages/news/[...slug].js

+import { useRouter } from 'next/router'
+import Link from 'next/link'
+import styles from '../../styles.module.css'
+
+const Code = (p) => <code className={styles.inlineCode} {...p} />
+
+export default function News() {
+  const { asPath, route, query } = useRouter()
+
+  return (
+    <div className={styles.container}>
+      <div className={styles.card}>
+        <h1>Path: {asPath}</h1>
+        <hr className={styles.hr} />
+        <p>
+          This page was rendered by <Code>{`pages${route}.js`}</Code>.
+        </p>
+        <p>
+          The query <Code>slug</Code> for this page is:{' '}
+          <Code>{JSON.stringify(query.slug)}</Code>
+        </p>
+        <Link href="/">
+          <a> &larr; Back home</a>
+        </Link>
+      </div>
+    </div>
+  )
+}
+
+// Use SSR for this page as currently rewrites don't work with dynamic pages without SSR
+export async function getServerSideProps(context) {
+  return {
+    props: {},
+  }
+}

examples/rewrites/styles.module.css

+.container {
+  padding: 4rem 1rem;
+  font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+}
+
+.container p {
+  margin: 1.5rem 0;
+}
+
+.card {
+  max-width: 50rem;
+  box-shadow: -10px 10px 80px rgba(0, 0, 0, 0.12);
+  border: 1px solid #eee;
+  border-radius: 8px;
+  padding: 2rem;
+  margin: 0 auto;
+}
+
+.inlineCode {
+  color: #be00ff;
+  font-size: 16px;
+  white-space: pre-wrap;
+}
+
+.inlineCode::before,
+.inlineCode::after {
+  content: '`';
+}
+
+.hr {
+  border: 0;
+  border-top: 1px solid #eaeaea;
+  margin: 1.5rem 0;
+}
+
+.list {
+  padding-left: 1.5rem;
+  margin: 1.25rem 0;
+  list-style-type: none;
+}
+
+.list li {
+  margin-bottom: 0.75rem;
+}
+
+.list li:before {
+  content: '-';
+  color: #999999;
+  position: absolute;
+  margin-left: -1rem;
+}