Add example for headers and link in the docs (#21821)

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

@@ -6,6 +6,13 @@ description: Add custom HTTP headers to your Next.js app.
 
 > This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
 
+<details open>
+  <summary><b>Examples</b></summary>
+  <ul>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/headers">Headers</a></li>
+  </ul>
+</details>
+
 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`:

examples/headers/.gitignore

@@ -0,0 +1,34 @@
+# 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/headers/README.md

@@ -0,0 +1,23 @@
+# Headers Example
+
+This example shows how to use [headers in Next.js](https://nextjs.org/docs/api-reference/next.config.js/headers) to add custom HTTP headers into your Next.js app.
+
+The index page ([`pages/index.js`](pages/index.js)) has a list of links to pages with custom headers set up 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?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/headers&project-name=headers&repository-name=headers)
+
+## 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 headers headers-app
+# or
+yarn create next-app --example headers headers-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).

examples/headers/next.config.js

@@ -0,0 +1,24 @@
+module.exports = {
+  async headers() {
+    return [
+      {
+        source: '/about',
+        headers: [
+          {
+            key: 'X-About-Custom-Header',
+            value: 'about_header_value',
+          },
+        ],
+      },
+      {
+        source: '/news/:id',
+        headers: [
+          {
+            key: 'X-News-Custom-Header',
+            value: 'news_header_value',
+          },
+        ],
+      },
+    ]
+  },
+}

examples/headers/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "headers",
+  "version": "1.0.0",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "next": "latest",
+    "react": "^16.13.1",
+    "react-dom": "^16.13.1"
+  },
+  "license": "MIT"
+}

examples/headers/pages/about.js

@@ -0,0 +1,27 @@
+import Link from 'next/link'
+import styles from '../styles.module.css'
+
+const Code = (p) => <code className={styles.inlineCode} {...p} />
+
+export default function About() {
+  return (
+    <div className={styles.container}>
+      <div className={styles.card}>
+        <h1>Path: /about</h1>
+        <hr className={styles.hr} />
+        <p>
+          The response contains a custom header{' '}
+          <Code>X-About-Custom-Header</Code> : <Code>about_header_value</Code>.
+        </p>
+        <p>
+          To check the response headers of this page, open the Network tab
+          inside your browser inspector.
+        </p>
+
+        <Link href="/">
+          <a> &larr; Back home</a>
+        </Link>
+      </div>
+    </div>
+  )
+}

examples/headers/pages/index.js

@@ -0,0 +1,40 @@
+import styles from '../styles.module.css'
+
+const Code = (p) => <code className={styles.inlineCode} {...p} />
+
+const Index = () => (
+  <div className={styles.container}>
+    <div className={styles.card}>
+      <h1>Headers with Next.js</h1>
+      <hr className={styles.hr} />
+      <p>
+        The links below are examples of{' '}
+        <a href="https://nextjs.org/docs/api-reference/next.config.js/headers">
+          custom <Code>headers</Code>
+        </a>{' '}
+        added to your Next.js app.
+      </p>
+      <nav>
+        <ul className={styles.list}>
+          <li>
+            <a href="/about">
+              <a>Visit /about (it contains a X-About-Custom-Header)</a>
+            </a>
+          </li>
+          <li>
+            <a href="/news/123">
+              <a>Visit /news/123 (it contains a X-News-Custom-Header)</a>
+            </a>
+          </li>
+        </ul>
+      </nav>
+      <p>
+        Open <Code>next.config.js</Code> to learn more about the headers that
+        match the links above.
+      </p>
+      <hr className={styles.hr} />
+    </div>
+  </div>
+)
+
+export default Index

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

@@ -0,0 +1,31 @@
+import { useRouter } from 'next/router'
+import Link from 'next/link'
+import styles from '../../styles.module.css'
+
+const Code = (p) => <code className={styles.inlineCode} {...p} />
+
+const News = ({ props }) => {
+  const { asPath } = useRouter()
+
+  return (
+    <div className={styles.container}>
+      <div className={styles.card}>
+        <h1>Path: {asPath}</h1>
+        <hr className={styles.hr} />
+        <p>
+          The response contains a custom header{' '}
+          <Code>X-News-Custom-Header</Code> : <Code>news_header_value</Code>.
+        </p>
+        <p>
+          To check the response headers of this page, open the Network tab
+          inside your browser inspector.
+        </p>
+        <Link href="/">
+          <a> &larr; Back home</a>
+        </Link>
+      </div>
+    </div>
+  )
+}
+
+export default News

examples/headers/styles.module.css

@@ -0,0 +1,51 @@
+.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;
+}