Merge branch 'canary' into firebase-auth-example-token-expiry

.github/workflows/build_test_deploy.yml

@@ -78,9 +78,8 @@ jobs:
       - run: exit 0
 
   testMacOS:
-    name: macOS ( Basic, Production, Acceptance )
+    name: macOS (Basic, Production, Acceptance)
     runs-on: macos-latest
-    needs: build
     env:
       NEXT_TELEMETRY_DISABLED: 1
       NEXT_TEST_JOB: 1
@@ -90,7 +89,24 @@ jobs:
       - uses: actions/checkout@v2
       - run: git fetch --depth=1 origin +refs/tags/*:refs/tags/*
       # Installing dependencies again since OS changed
-      - run: yarn install --frozen-lockfile --check-files
+      - run: yarn install --frozen-lockfile --check-files || yarn install --frozen-lockfile --check-files
+      - run: node run-tests.js test/integration/production/test/index.test.js
+      - run: node run-tests.js test/integration/basic/test/index.test.js
+      - run: node run-tests.js test/acceptance/*
+
+  testWebpack5:
+    name: webpack 5 (Basic, Production, Acceptance)
+    runs-on: ubuntu-latest
+    env:
+      NEXT_TELEMETRY_DISABLED: 1
+      NEXT_TEST_JOB: 1
+      HEADLESS: true
+
+    steps:
+      - uses: actions/checkout@v2
+      - run: git fetch --depth=1 origin +refs/tags/*:refs/tags/*
+      - run: cat package.json | jq '.resolutions.webpack = "^5.0.0-beta.22"' > package.json.tmp && mv package.json.tmp package.json
+      - run: yarn install --check-files
       - run: node run-tests.js test/integration/production/test/index.test.js
       - run: node run-tests.js test/integration/basic/test/index.test.js
       - run: node run-tests.js test/acceptance/*

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

@@ -4,6 +4,8 @@ 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.
+
 To deploy a Next.js application under a sub-path of a domain you can use the `basePath` option.
 
 `basePath` allows you to set a path prefix for the application. For example `/docs` instead of `/` (the default).

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

@@ -4,6 +4,8 @@ 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.
+
 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`:
@@ -90,6 +92,28 @@ module.exports = {
 }
 ```
 
+### Regex Path Matching
+
+To match a regex path you can wrap the regex in parenthesis after a parameter, for example `/blog/:slug(\\d{1,})` will match `/blog/123` but not `/blog/abc`:
+
+```js
+module.exports = {
+  async rewrites() {
+    return [
+      {
+        source: '/blog/:post(\\d{1,})',
+        headers: [
+          {
+            key: 'x-post',
+            value: ':post',
+          },
+        ],
+      },
+    ]
+  },
+}
+```
+
 ### Headers with basePath support
 
 When leveraging [`basePath` support](/docs/api-reference/next.config.js/basepath.md) with headers each `source` is automatically prefixed with the `basePath` unless you add `basePath: false` to the header:

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

@@ -4,6 +4,8 @@ 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.
+
 Redirects allow you to redirect an incoming request path to a different destination path.
 
 Redirects are only available on the Node.js environment and do not affect client-side routing.
@@ -66,6 +68,24 @@ module.exports = {
 }
 ```
 
+### Regex Path Matching
+
+To match a regex path you can wrap the regex in parenthesis after a parameter, for example `/blog/:slug(\\d{1,})` will match `/blog/123` but not `/blog/abc`:
+
+```js
+module.exports = {
+  async redirects() {
+    return [
+      {
+        source: '/old-blog/:post(\\d{1,})',
+        destination: '/blog/:post', // Matched parameters can be used in the destination
+        permanent: false,
+      },
+    ]
+  },
+}
+```
+
 ### Redirects with basePath support
 
 When leveraging [`basePath` support](/docs/api-reference/next.config.js/basepath.md) with redirects each `source` and `destination` is automatically prefixed with the `basePath` unless you add `basePath: false` to the redirect:

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

@@ -4,7 +4,9 @@ description: Add rewrites to your Next.js app.
 
 # Rewrites
 
-<details>
+> 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/rewrites">Rewrites</a></li>
@@ -69,6 +71,23 @@ module.exports = {
 }
 ```
 
+### Regex Path Matching
+
+To match a regex path you can wrap the regex in parenthesis after a parameter, for example `/blog/:slug(\\d{1,})` will match `/blog/123` but not `/blog/abc`:
+
+```js
+module.exports = {
+  async rewrites() {
+    return [
+      {
+        source: '/old-blog/:post(\\d{1,})',
+        destination: '/blog/:post', // Matched parameters can be used in the destination
+      },
+    ]
+  },
+}
+```
+
 ## Rewriting to an external URL
 
 <details>

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

@@ -4,6 +4,8 @@ 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.
+
 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.
 
 Open `next.config.js` and add the `trailingSlash` config:

docs/basic-features/built-in-css-support.md

@@ -4,6 +4,14 @@ description: Next.js supports including CSS files as Global CSS or CSS Modules,
 
 # Built-In CSS Support
 
+<details open>
+  <summary><b>Examples</b></summary>
+  <ul>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/basic-css">Basic CSS Example</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-tailwindcss">With Tailwind CSS</a></li>
+  </ul>
+</details>
+
 Next.js allows you to import CSS files from a JavaScript file.
 This is possible because Next.js extends the concept of [`import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) beyond JavaScript.
 
@@ -143,8 +151,10 @@ Error: Cannot find module 'less'
 <details>
   <summary><b>Examples</b></summary>
   <ul>
-    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/basic-css">Styled JSX</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-styled-jsx">Styled JSX</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-styled-components">Styled Components</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-emotion">Emotion</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-tailwindcss-emotion">Tailwind CSS + Emotion</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-styletron">Styletron</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-glamor">Glamor</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-cxs">Cxs</a></li>

docs/basic-features/data-fetching.md

@@ -54,6 +54,11 @@ The `context` parameter is an object containing the following keys:
 - `preview` is `true` if the page is in the preview mode and `false` otherwise. See the [Preview Mode documentation](/docs/advanced-features/preview-mode.md).
 - `previewData` contains the preview data set by `setPreviewData`. See the [Preview Mode documentation](/docs/advanced-features/preview-mode.md).
 
+`getStaticProps` should return an object with:
+
+- `props` - A **required** object with the props that will be received by the page component. It should be a [serializable object](https://en.wikipedia.org/wiki/Serialization)
+- `revalidate` - An **optional** amount in seconds after which a page re-generation can occur. More on [Incremental Static Regeneration](#incremental-static-regeneration)
+
 > **Note**: You can import modules in top-level scope for use in `getStaticProps`.
 > Imports used in `getStaticProps` will not be bundled for the client-side, as [explained below](#write-server-side-code-directly).
 
@@ -143,6 +148,67 @@ function Blog({ posts }: InferGetStaticPropsType<typeof getStaticProps>) {
 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.now.sh/">Static Reactions Demo</a></li>
+  </ul>
+</details>
+
+With [`getStaticProps`](#getstaticprops-static-generation) you don't have to stop relying in 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.
+
+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.
+
+Consider our previous [`getStaticProps` example](#simple-example), but now with regeneration enabled:
+
+```jsx
+function Blog({ posts }) {
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li>{post.title}</li>
+      ))}
+    </ul>
+  )
+}
+
+// This function gets called at build time on server-side.
+// It may be called again, on a serverless function, if
+// revalidation is enabled and a new request comes in
+export async function getStaticProps() {
+  const res = await fetch('https://.../posts')
+  const posts = await res.json()
+
+  return {
+    props: {
+      posts,
+    },
+    // Next.js will attempt to re-generate the page:
+    // - When a request comes in
+    // - At most once every second
+    revalidate: 1, // In seconds
+  }
+}
+
+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.
+
+#### Static content at scale
+
+Unlike traditional SSR, [Incremental Static Regeneration](#incremental-static-regeneration) ensures you retain the benefits of static:
+
+- 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
+
 ### Reading files: Use `process.cwd()`
 
 Files can be read directly from the filesystem in `getStaticProps`.
@@ -387,7 +453,12 @@ export async function getStaticProps({ params }) {
   const post = await res.json()
 
   // Pass post data to the page via props
-  return { props: { post } }
+  return {
+    props: { post },
+    // Re-generate the post at most once per second
+    // if a request comes in
+    revalidate: 1,
+  }
 }
 
 export default Post
@@ -401,6 +472,8 @@ Instead, you may statically generate a small subset of pages and use `fallback:
 
 This ensures that users always have a fast experience while preserving fast builds and the benefits of Static Generation.
 
+`fallback: true` will not _update_ generated pages, for that take a look at [Incremental Static Regeneration](#incremental-static-regeneration).
+
 ### When should I use `getStaticPaths`?
 
 You should use `getStaticPaths` if you’re statically pre-rendering pages that use dynamic routes.

docs/create-next-app.md

@@ -0,0 +1,55 @@
+---
+description: Create Next.js apps in one command with create-next-app.
+---
+
+# Create Next App
+
+The easiest way to get started with Next.js is by using `create-next-app`. This simple CLI tool enables you to quickly start building a new Next.js application, with everything set up for you. You can create a new app using the default Next.js template, or by using one of the [official Next.js examples](https://github.com/vercel/next.js/tree/canary/examples). To get started, use the following command:
+
+```bash
+npx create-next-app
+# or
+yarn create next-app
+```
+
+### Options
+
+`create-next-app` comes with the following options:
+
+- **-e, --example [name]|[github-url]** - An example to bootstrap the app with. You can use an example name from the [Next.js repo](https://github.com/vercel/next.js/tree/master/examples) or a GitHub URL. The URL can use any branch and/or subdirectory.
+- **--example-path [path-to-example]** - In a rare case, your GitHub URL might contain a branch name with a slash (e.g. bug/fix-1) and the path to the example (e.g. foo/bar). In this case, you must specify the path to the example separately: `--example-path foo/bar`
+
+### Why use Create Next App?
+
+`create-next-app` allows you to create a new Next.js app within seconds. It is officially maintained by the creators of Next.js, and includes a number of benefits:
+
+- **Interactive Experience**: Running `npx create-next-app` (with no arguments) launches an interactive experience that guides you through setting up a project.
+- **Zero Dependencies**: Initializing a project is as quick as one second. Create Next App has zero dependencies.
+- **Offline Support**: Create Next App will automatically detect if you're offline and bootstrap your project using your local package cache.
+- **Support for Examples**: Create Next App can bootstrap your application using an example from the Next.js examples collection (e.g. `npx create-next-app --example api-routes`).
+- **Tested**: The package is part of the Next.js monorepo and tested using the same integration test suite as Next.js itself, ensuring it works as expected with every release.
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+<div class="card">
+  <a href="/docs/basic-features/pages.md">
+    <b>Pages:</b>
+    <small>Learn more about what pages are in Next.js.</small>
+  </a>
+</div>
+
+<div class="card">
+  <a href="/docs/basic-features/built-in-css-support.md">
+    <b>CSS Support:</b>
+    <small>Use the built-in CSS support to add custom styles to your app.</small>
+  </a>
+</div>
+
+<div class="card">
+  <a href="/docs/api-reference/cli.md">
+    <b>CLI:</b>
+    <small>Learn more about the Next.js CLI.</small>
+  </a>
+</div>

docs/deployment.md

@@ -40,7 +40,7 @@ By using the DPS workflow, in addition to doing _code reviews_, you can do _depl
 For example, the [hybrid pages](/docs/basic-features/pages.md) approach is fully supported out of the box.
 
 - Every page can either use [Static Generation](/docs/basic-features/pages.md#static-generation) or [Server-Side Rendering](/docs/basic-features/pages.md#server-side-rendering).
-- Pages that use [Static Generation](/docs/basic-features/pages.md#static-generation) and assets (JS, CSS, images, fonts, etc) will automatically be served from the [Vercel Smart CDN](https://vercel.com/smart-cdn), which is blazingly fast.
+- Pages that use [Static Generation](/docs/basic-features/pages.md#static-generation) and assets (JS, CSS, images, fonts, etc) will automatically be served from the [Vercel's Edge Network](https://vercel.com/docs/v2/edge-network/overview), which is blazingly fast.
 - Pages that use [Server-Side Rendering](/docs/basic-features/pages.md#server-side-rendering) and [API routes](/docs/api-routes/introduction.md) will automatically become isolated Serverless Functions. This allows page rendering and API requests to scale infinitely.
 
 ### Custom Domains, Environment Variables, Automatic HTTPS, and more

docs/getting-started.md

@@ -29,6 +29,8 @@ yarn create next-app
 
 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/create-next-app.md)
+
 ## Manual Setup
 
 Install `next`, `react` and `react-dom` in your project:
@@ -41,19 +43,19 @@ Open `package.json` and add the following `scripts`:
 
 ```json
 "scripts": {
-  "dev": "next",
+  "dev": "next dev",
   "build": "next build",
   "start": "next start"
 }
 ```
 
 These scripts refer to the different stages of developing an application:
 
-- `dev` - Runs `next` which starts Next.js in development mode
-- `build` - Runs `next build` which builds the application for production usage
-- `start` - Runs `next start` which starts a Next.js production server
+- `dev` - Runs [`next dev`](/docs/api-reference/cli#development) which starts Next.js in development mode
+- `build` - Runs [`next build`](/docs/api-reference/cli#build) which builds the application for production usage
+- `start` - Runs [`next start`](/docs/api-reference/cli#production) which starts a Next.js production server
 
-Next.js is built around the concept of pages. A page is a [React Component](https://reactjs.org/docs/components-and-props.html) exported from a `.js`, `.jsx`, `.ts`, or `.tsx` file in the `pages` directory.
+Next.js is built around the concept of [pages](/docs/basic-features/pages.md). A page is a [React Component](https://reactjs.org/docs/components-and-props.html) exported from a `.js`, `.jsx`, `.ts`, or `.tsx` file in the `pages` directory.
 
 Pages are associated with a route based on their file name. For example `pages/about.js` is mapped to `/about`. You can even add dynamic route parameters with the filename.
 

docs/routing/dynamic-routes.md

@@ -108,5 +108,6 @@ The `query` objects are as follows:
   - `pages/post/[pid].js` - Will match `/post/1`, `/post/abc`, etc. But not `/post/create`
   - `pages/post/[...slug].js` - Will match `/post/1/2`, `/post/a/b/c`, etc. But not `/post/create`, `/post/abc`
 - Pages that are statically optimized by [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) will be hydrated without their route parameters provided, i.e `query` will be an empty object (`{}`).
+- When routing to a dynamic route using `Link` or `router`, you will need to specify the `href` as the dynamic route, for example `/post/[pid]` and `as` as the decorator for the URL, for example `/post/abc`.
 
   After hydration, Next.js will trigger an update to your application to provide the route parameters in the `query` object.