Merge branch 'canary' into fix/24772

.eslintignore

@@ -17,6 +17,7 @@ packages/next-codemod/transforms/__tests__/**/*
 packages/next-codemod/**/*.js
 packages/next-codemod/**/*.d.ts
 packages/next-env/**/*.d.ts
+packages/create-next-app/templates/**
 test/integration/async-modules/**
 test/integration/eslint/**
 test-timings.json

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

@@ -4,7 +4,14 @@ description: Learn more about setting a base path in Next.js
 
 # Base Path
 
-> 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>
+  <summary><b>Version History</b></summary>
+
+| Version  | Changes          |
+| -------- | ---------------- |
+| `v9.5.0` | Base Path added. |
+
+</details>
 
 To deploy a Next.js application under a sub-path of a domain you can use the `basePath` config option.
 

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

@@ -4,8 +4,6 @@ description: Add custom HTTP headers to your Next.js app.
 
 # Headers
 
-> 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>
@@ -16,9 +14,10 @@ description: Add custom HTTP headers to your Next.js app.
 <details>
   <summary><b>Version History</b></summary>
 
-| Version   | Changes      |
-| --------- | ------------ |
-| `v10.2.0` | `has` added. |
+| Version   | Changes        |
+| --------- | -------------- |
+| `v10.2.0` | `has` added.   |
+| `v9.5.0`  | Headers added. |
 
 </details>
 

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

@@ -4,8 +4,6 @@ description: Add redirects to your Next.js app.
 
 # Redirects
 
-> 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>
@@ -16,9 +14,10 @@ description: Add redirects to your Next.js app.
 <details>
   <summary><b>Version History</b></summary>
 
-| Version   | Changes      |
-| --------- | ------------ |
-| `v10.2.0` | `has` added. |
+| Version   | Changes          |
+| --------- | ---------------- |
+| `v10.2.0` | `has` added.     |
+| `v9.5.0`  | Redirects added. |
 
 </details>
 

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

@@ -4,8 +4,6 @@ description: Add rewrites to your Next.js app.
 
 # Rewrites
 
-> 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>
@@ -16,14 +14,17 @@ description: Add rewrites to your Next.js app.
 <details>
   <summary><b>Version History</b></summary>
 
-| Version   | Changes      |
-| --------- | ------------ |
-| `v10.2.0` | `has` added. |
+| Version   | Changes         |
+| --------- | --------------- |
+| `v10.2.0` | `has` added.    |
+| `v9.5.0`  | Rewrites added. |
 
 </details>
 
 Rewrites allow you to map an incoming request path to a different destination path.
 
+Rewrites act as a URL proxy and mask the destination path, making it appear the user hasn't changed their location on the site. In contrast, [redirects](/docs/api-reference/next.config.js/redirects.md) will reroute to a new page a show the URL changes.
+
 Rewrites are only available on the Node.js environment and do not affect client-side routing.
 
 To use rewrites you can use the `rewrites` key in `next.config.js`:
@@ -326,7 +327,7 @@ module.exports = {
 }
 ```
 
-See additional information on incremental adoption [in the docs here](https://nextjs.org/docs/migrating/incremental-adoption).
+See additional information on incremental adoption [in the docs here](/docs/migrating/incremental-adoption.md).
 
 ### Rewrites with basePath support
 

docs/api-reference/next.config.js/trailing-slash.md

@@ -4,7 +4,14 @@ description: Configure Next.js pages to resolve with or without a trailing slash
 
 # Trailing Slash
 
-> 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>
+  <summary><b>Version History</b></summary>
+
+| Version  | Changes               |
+| -------- | --------------------- |
+| `v9.5.0` | Trailing Slash added. |
+
+</details>
 
 By default Next.js will redirect urls with trailing slashes to their counterpart without a trailing slash. For example `/about/` will redirect to `/about`. You can configure this behavior to act the opposite way, where urls without trailing slashes are redirected to their counterparts with trailing slashes.
 

docs/basic-features/data-fetching.md

@@ -222,20 +222,27 @@ export default Blog
 
 ### Incremental Static Regeneration
 
-> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5#stable-incremental-static-regeneration) and up. If you’re using older versions of Next.js, please upgrade before trying Incremental Static Regeneration.
-
 <details open>
   <summary><b>Examples</b></summary>
   <ul>
-    <li><a href="https://reactions-demo.vercel.app/">Static Reactions Demo</a></li>
+    <li><a href="https://nextjs.org/commerce">Next.js Commerce</a></li>
+    <li><a href="https://reactions-demo.vercel.app/">GitHub Reactions Demo</a></li>
+    <li><a href="https://static-tweet.vercel.app/">Static Tweet Demo</a></li>
   </ul>
 </details>
 
-With [`getStaticProps`](#getstaticprops-static-generation) you don't have to stop relying on dynamic content, as **static content can also be dynamic**. Incremental Static Regeneration allows you to update _existing_ pages by re-rendering them in the background as traffic comes in.
+<details>
+  <summary><b>Version History</b></summary>
+
+| Version  | Changes          |
+| -------- | ---------------- |
+| `v9.5.0` | Base Path added. |
 
-Inspired by [stale-while-revalidate](https://tools.ietf.org/html/rfc5861), background regeneration ensures traffic is served uninterruptedly, always from static storage, and the newly built page is pushed only after it's done generating.
+</details>
 
-Consider our previous [`getStaticProps` example](#simple-example), but now with regeneration enabled:
+Next.js allows you to create or update static pages _after_ you’ve built your site. Incremental Static Regeneration (ISR) enables you to use static-generation on a per-page basis, **without needing to rebuild the entire site**. With ISR, you can retain the benefits of static while scaling to millions of pages.
+
+Consider our previous [`getStaticProps` example](#simple-example), but now with Incremental Static Regeneration enabled through the `revalidate` property:
 
 ```jsx
 function Blog({ posts }) {
@@ -261,25 +268,42 @@ export async function getStaticProps() {
     },
     // Next.js will attempt to re-generate the page:
     // - When a request comes in
-    // - At most once every second
-    revalidate: 1, // In seconds
+    // - At most once every 10 seconds
+    revalidate: 10, // In seconds
   }
 }
 
+// This function gets called at build time on server-side.
+// It may be called again, on a serverless function, if
+// the path has not been generated.
+export async function getStaticPaths() {
+  const res = await fetch('https://.../posts')
+  const posts = await res.json()
+
+  // Get the paths we want to pre-render based on posts
+  const paths = posts.map((post) => ({
+    params: { id: post.id },
+  }))
+
+  // We'll pre-render only these paths at build time.
+  // { fallback: blocking } will server-render pages
+  // on-demand if the path doesn't exist.
+  return { paths, fallback: 'blocking' }
+}
+
 export default Blog
 ```
 
-Now the list of blog posts will be revalidated once per second; if you add a new blog post it will be available almost immediately, without having to re-build your app or make a new deployment.
-
-This works perfectly with [`fallback: true`](#fallback-true). Because now you can have a list of posts that's always up to date with the latest posts, and have a [blog post page](#fallback-pages) that generates blog posts on-demand, no matter how many posts you add or update.
+When a request is made to a page that was pre-rendered at build time, it will initially show the cached page.
 
-#### Static content at scale
+- Any requests to the page after the initial request and before 10 seconds are also cached and instantaneous.
+- After the 10-second window, the next request will still show the cached (stale) page
+- Next.js triggers a regeneration of the page in the background.
+- Once the page has been successfully generated, Next.js will invalidate the cache and show the updated product page. If the background regeneration fails, the old page remains unaltered.
 
-Unlike traditional SSR, [Incremental Static Regeneration](#incremental-static-regeneration) ensures you retain the benefits of static:
+When a request is made to a path that hasn’t been generated, Next.js will server-render the page on the first request. Future requests will serve the static file from the cache.
 
-- No spikes in latency. Pages are served consistently fast
-- Pages never go offline. If the background page re-generation fails, the old page remains unaltered
-- Low database and backend load. Pages are re-computed at most once concurrently
+To learn how to persist the cache globally and handle rollbacks, learn more about [Incremental Static Regeneration](https://vercel.com/docs/next.js/incremental-static-regeneration).
 
 ### Reading files: Use `process.cwd()`
 

docs/getting-started.md

@@ -27,6 +27,14 @@ npx create-next-app
 yarn create next-app
 ```
 
+If you want to start with a TypeScript project you can use the `--typescript` flag:
+
+```bash
+npx create-next-app --typescript
+# or
+yarn create next-app --typescript
+```
+
 After the installation is complete, follow the instructions to start the development server. Try editing `pages/index.js` and see the result on your browser.
 
 For more information on how to use `create-next-app`, you can review the [`create-next-app` documentation](/docs/api-reference/create-next-app.md)

errors/manifest.json

@@ -267,6 +267,10 @@
           "title": "no-sync-scripts",
           "path": "/errors/no-sync-scripts.md"
         },
+        {
+          "title": "no-title-in-document-head",
+          "path": "/errors/no-title-in-document-head.md"
+        },
         {
           "title": "no-unwanted-polyfillio",
           "path": "/errors/no-unwanted-polyfillio.md"

errors/no-title-in-document-head.md

@@ -0,0 +1,30 @@
+# No Title in Document Head
+
+### Why This Error Occurred
+
+A `<title>` element was defined within the `Head` component imported from `next/document`, which should only be used for any `<head>` code that is common for all pages. Title tags should be defined at the page-level using `next/head`.
+
+### Possible Ways to Fix It
+
+Within a page or component, import and use `next/head` to define a page title:
+
+```jsx
+import Head from 'next/head'
+
+export class Home {
+  render() {
+    return (
+      <div>
+        <Head>
+          <title>My page title</title>
+        </Head>
+      </div>
+    )
+  }
+}
+```
+
+### Useful links
+
+- [next/head](https://nextjs.org/docs/api-reference/next/head)
+- [Custom Document](https://nextjs.org/docs/advanced-features/custom-document)

examples/custom-server-express/README.md

@@ -1,10 +1,8 @@
 # Custom Express Server example
 
-Most of the time the default Next.js server will be enough but there are times you'll want to run your own server to customize routes or other kinds of app behavior. Next.js provides [Custom server and routing](https://github.com/vercel/next.js#custom-server-and-routing) options, so you can customize as much as you want.
+Most of the time the default Next.js server will be enough but there are times you'll want to run your own server to integrate into an existing application. Next.js provides [a custom server api](https://nextjs.org/docs/advanced-features/custom-server).
 
-Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. In this case we are using express to build a custom router on top of Next.
-
-This example demonstrates a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`.
+Because the Next.js server is a Node.js module you can combine it with any other part of the Node.js ecosystem. In this case we are using express.
 
 ## How to use
 
@@ -15,15 +13,3 @@ npx create-next-app --example custom-server-express custom-server-express-app
 # or
 yarn create next-app --example custom-server-express custom-server-express-app
 ```
-
-### Populate body property
-
-Without the use of body parsing middleware `req.body` will return undefined. To get express to populate `req.body` you need to use middleware within server.js:
-
-```js
-app.prepare().then(() => {
-  const server = express()
-  server.use(express.urlencoded({ extended: true }))
-  server.use(express.json())
-})
-```

examples/custom-server-express/server.js

@@ -9,14 +9,6 @@ const handle = app.getRequestHandler()
 app.prepare().then(() => {
   const server = express()
 
-  server.get('/a', (req, res) => {
-    return app.render(req, res, '/a', req.query)
-  })
-
-  server.get('/b', (req, res) => {
-    return app.render(req, res, '/b', req.query)
-  })
-
   server.all('*', (req, res) => {
     return handle(req, res)
   })

examples/custom-server-hapi/README.md

@@ -1,10 +1,8 @@
 # Custom server using Hapi example
 
-Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/vercel/next.js#custom-server-and-routing) so you can customize as much as you want.
+Most of the time the default Next.js server will be enough but there are times you'll want to run your own server to integrate into an existing application. Next.js provides [a custom server api](https://nextjs.org/docs/advanced-features/custom-server).
 
-Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using [Hapi](https://hapijs.com) to build a custom router on top of Next.
-
-The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`.
+Because the Next.js server is a Node.js module you can combine it with any other part of the node.js ecosystem. In this case we are using [Hapi](https://hapijs.com).
 
 ## How to use
 

examples/custom-server-hapi/server.js

@@ -1,6 +1,6 @@
 const next = require('next')
 const Hapi = require('@hapi/hapi')
-const { pathWrapper, nextHandlerWrapper } = require('./next-wrapper')
+const { /* pathWrapper, */ nextHandlerWrapper } = require('./next-wrapper')
 
 const port = parseInt(process.env.PORT, 10) || 3000
 const dev = process.env.NODE_ENV !== 'production'
@@ -10,18 +10,6 @@ const server = new Hapi.Server({
 })
 
 app.prepare().then(async () => {
-  server.route({
-    method: 'GET',
-    path: '/a',
-    handler: pathWrapper(app, '/a'),
-  })
-
-  server.route({
-    method: 'GET',
-    path: '/b',
-    handler: pathWrapper(app, '/b'),
-  })
-
   server.route({
     method: 'GET',
     path: '/_next/{p*}' /* next specific routes */,

examples/custom-server-koa/README.md

@@ -1,10 +1,8 @@
 # Custom Koa Server example
 
-Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://nextjs.org/docs/advanced-features/custom-server) so you can customize as much as you want.
+Most of the time the default Next.js server will be enough but there are times you'll want to run your own server to integrate into an existing application. Next.js provides [a custom server api](https://nextjs.org/docs/advanced-features/custom-server).
 
-Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using [Koa](https://koajs.com/) to build a custom router on top of Next.
-
-The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`.
+Because the Next.js server is a Node.js module you can combine it with any other part of the Node.js ecosystem. In this case we are using [Koa](https://koajs.com/).
 
 ## How to use
 

examples/custom-server-koa/server.js

@@ -11,16 +11,6 @@ app.prepare().then(() => {
   const server = new Koa()
   const router = new Router()
 
-  router.get('/a', async (ctx) => {
-    await app.render(ctx.req, ctx.res, '/a', ctx.query)
-    ctx.respond = false
-  })
-
-  router.get('/b', async (ctx) => {
-    await app.render(ctx.req, ctx.res, '/b', ctx.query)
-    ctx.respond = false
-  })
-
   router.all('(.*)', async (ctx) => {
     await handle(ctx.req, ctx.res)
     ctx.respond = false

examples/custom-server-polka/README.md

@@ -1,10 +1,8 @@
 # Custom [Polka](https://github.com/lukeed/polka) Server example
 
-Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/vercel/next.js#custom-server-and-routing) so you can customize as much as you want.
+Most of the time the default Next.js server will be enough but there are times you'll want to run your own server to integrate into an existing application. Next.js provides [a custom server api](https://nextjs.org/docs/advanced-features/custom-server).
 
-Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using express to build a custom router on top of Next.
-
-The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`.
+Because the Next.js server is a Node.js module you can combine it with any other part of the Node.js ecosystem. In this case we are using Polka.
 
 ## How to use