Merge branch 'canary' into feat-external-dir

.github/CODEOWNERS

@@ -1,6 +1,6 @@
 # Learn how to add code owners here:
 # https://help.github.com/en/articles/about-code-owners
 
-*          @timneutkens @Timer @ijjk @lfades @divmain
-/docs/     @timneutkens @Timer @ijjk @lfades @divmain @leerob
-/examples/ @timneutkens @Timer @ijjk @lfades @divmain @leerob
+*          @timneutkens @ijjk @lfades @divmain @shuding
+/docs/     @timneutkens @ijjk @lfades @divmain @shuding @leerob
+/examples/ @timneutkens @ijjk @lfades @divmain @shuding @leerob

.github/pull_request_template.md

@@ -0,0 +1,22 @@
+<!--
+Thanks for opening a PR! Your contribution is much appreciated.
+In order to make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below.
+Choose the right checklist for the change that you're making:
+-->
+
+## Bug
+
+- [ ] Related issues linked using `fixes #number`
+- [ ] Integration tests added
+
+## Feature
+
+- [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
+- [ ] Related issues linked using `fixes #number`
+- [ ] Integration tests added
+- [ ] Documentation added
+- [ ] Telemetry added. In case of a feature if it's used or not.
+
+## Documentation / Examples
+
+- [ ] Make sure the linting passes

docs/advanced-features/custom-error-page.md

@@ -25,9 +25,22 @@ export default function Custom404() {
 
 ## 500 Page
 
-By default Next.js provides a 500 error page that matches the default 404 page’s style. This page is not statically optimized as it allows server-side errors to be reported. This is why 404 and 500 (other errors) are separated.
+Server-rendering an error page for every visit adds complexity to responding to errors. To help users get responses to errors as fast as possible, Next.js provides a static 500 page by default without having to add any additional files.
 
-### Customizing The Error Page
+### Customizing The 500 Page
+
+To customize the 500 page you can create a `pages/500.js` file. This file is statically generated at build time.
+
+```jsx
+// pages/500.js
+export default function Custom500() {
+  return <h1>500 - Server-side error occurred</h1>
+}
+```
+
+> **Note**: You can use [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) inside this page if you need to fetch data at build time.
+
+### More Advanced Error Page Customizing
 
 500 errors are handled both client-side and server-side by the `Error` component. If you wish to override it, define the file `pages/_error.js` and add the following code:
 

docs/advanced-features/custom-server.md

@@ -15,7 +15,7 @@ description: Start a Next.js app programmatically using a custom server.
   </ul>
 </details>
 
-Typically you start your next server with `next start`. It's possible, however, to start a server 100% programmatically in order to use custom route patterns.
+By default, Next.js includes its own server with `next start`. If you have an existing backend, you can still use it with Next.js (this is not a custom server). A custom Next.js server allows you to start a server 100% programmatically in order to use custom server patterns. Most of the time, you will not need this – but it's available for complete customization.
 
 > A custom server **can not** be deployed on [Vercel](https://vercel.com/solutions/nextjs), the platform Next.js was made for.
 

docs/advanced-features/module-path-aliases.md

@@ -15,6 +15,8 @@ Next.js automatically supports the `tsconfig.json` and `jsconfig.json` `"paths"`
 
 > Note: `jsconfig.json` can be used when you don't use TypeScript
 
+> Note: you need to restart dev server to reflect modifications done in `tsconfig.json` / `jsconfig.json`
+
 These options allow you to configure module aliases, for example a common pattern is aliasing certain directories to use absolute paths.
 
 One useful feature of these options is that they integrate automatically into certain editors, for example vscode.

docs/advanced-features/source-maps.md

@@ -4,7 +4,7 @@ description: Enables browser source map generation during the production build.
 
 # Source Maps
 
-Source Maps are enabled by default during development. During production builds they are disabled as generation source maps can significantly increase build times and memory usage while being generated.
+Source Maps are enabled by default during development. During production builds, they are disabled as generating source maps can significantly increase build times and memory usage while being generated.
 
 Next.js provides a configuration flag you can use to enable browser source map generation during the production build:
 
@@ -15,9 +15,9 @@ module.exports = {
 }
 ```
 
-When the `productionBrowserSourceMaps` option is enabled the source maps will be output in the same directory as the JavaScript files, Next.js will automatically serve these files when requested.
+When the `productionBrowserSourceMaps` option is enabled, the source maps will be output in the same directory as the JavaScript files. Next.js will automatically serve these files when requested.
 
 ## Caveats
 
-- Can increase `next build` time
+- Adding source maps can increase `next build` time
 - Increases memory usage during `next build`

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

@@ -22,7 +22,7 @@ Note: this value must be set at build time and can not be changed without re-bui
 
 When linking to other pages using `next/link` and `next/router` the `basePath` will be automatically applied.
 
-For example using `/about` will automatically become `/docs/about` when `basePath` is set to `/docs`.
+For example, using `/about` will automatically become `/docs/about` when `basePath` is set to `/docs`.
 
 ```js
 export default function HomePage() {
@@ -43,3 +43,30 @@ Output html:
 ```
 
 This makes sure that you don't have to change all links in your application when changing the `basePath` value.
+
+## Images
+
+When using the [`next/image`](/docs/api-reference/next/image.md) component, you will need to add the `basePath` in front of `src`.
+
+For example, using `/docs/me.png` will properly serve your image when `basePath` is set to `/docs`.
+
+```jsx
+import Image from 'next/image'
+
+function Home() {
+  return (
+    <>
+      <h1>My Homepage</h1>
+      <Image
+        src="/docs/me.png"
+        alt="Picture of the author"
+        width={500}
+        height={500}
+      />
+      <p>Welcome to my homepage!</p>
+    </>
+  )
+}
+
+export default Home
+```

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

@@ -44,7 +44,7 @@ module.exports = (phase, { defaultConfig }) => {
 }
 ```
 
-The commented lines are the place where you can put the configs allowed by `next.config.js`, which are defined [here](https://github.com/vercel/next.js/blob/canary/packages/next/next-server/server/config.ts#L12-L63).
+The commented lines are the place where you can put the configs allowed by `next.config.js`, which are defined [here](https://github.com/vercel/next.js/blob/canary/packages/next/next-server/server/config-shared.ts#L33).
 
 However, none of the configs are required, and it's not necessary to understand what each config does. Instead, search for the features you need to enable or modify in this section and they will show you what to do.
 

docs/api-reference/next/router.md

@@ -72,7 +72,7 @@ router.push(url, as, options)
 - `url` - The URL to navigate to
 - `as` - Optional decorator for the URL that will be shown in the browser. Before Next.js 9.5.3 this was used for dynamic routes, check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes) to see how it worked
 - `options` - Optional object with the following configuration options:
-  - `scroll`: Scroll to the top of the page after a navigation. Defaults to `true`
+  - `scroll` - Optional boolean, controls scrolling to the top of the page after navigation. Defaults to `true`
   - [`shallow`](/docs/routing/shallow-routing.md): Update the path of the current page without rerunning [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation), [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering) or [`getInitialProps`](/docs/api-reference/data-fetching/getInitialProps.md). Defaults to `false`
 
 > You don't need to use `router.push` for external URLs. [window.location](https://developer.mozilla.org/en-US/docs/Web/API/Window/location) is better suited for those cases.

docs/authentication.md

@@ -119,10 +119,8 @@ Now that we've discussed authentication patterns, let's look at specific provide
 
 If you have an existing database with user data, you'll likely want to utilize an open-source solution that's provider agnostic.
 
-- If you need email/password log-in, use [`next-iron-session`](https://github.com/vercel/next.js/tree/canary/examples/with-iron-session).
-- If you need to persist session data on the server, use [`next-auth`](https://github.com/nextauthjs/next-auth-example).
-- If you need to support social login (Google, Facebook, etc.), use [`next-auth`](https://github.com/nextauthjs/next-auth-example).
-- If you want to use [JWTs](https://jwt.io/), use [`next-auth`](https://github.com/nextauthjs/next-auth-example).
+- If you want a low-level, encrypted, and stateless session utility use [`next-iron-session`](https://github.com/vercel/next.js/tree/canary/examples/with-iron-session).
+- If you want a full-featured authentication system with built-in providers (Google, Facebook, GitHub…), JWT, JWE, email/password, magic links and more… use [`next-auth`](https://github.com/nextauthjs/next-auth-example).
 
 Both of these libraries support either authentication pattern. If you're interested in [Passport](http://www.passportjs.org/), we also have examples for it using secure and encrypted cookies:
 

docs/basic-features/data-fetching.md

@@ -87,7 +87,7 @@ The `context` parameter is an object containing the following keys:
     }
 
     return {
-      props: {}, // will be passed to the page component as props
+      props: { data }, // will be passed to the page component as props
     }
   }
   ```
@@ -111,7 +111,7 @@ The `context` parameter is an object containing the following keys:
     }
 
     return {
-      props: {}, // will be passed to the page component as props
+      props: { data }, // will be passed to the page component as props
     }
   }
   ```
@@ -156,7 +156,7 @@ export async function getStaticProps() {
   const res = await fetch('https://.../posts')
   const posts = await res.json()
 
-  // By returning { props: posts }, the Blog component
+  // By returning { props: { posts } }, the Blog component
   // will receive `posts` as a prop at build time
   return {
     props: {
@@ -325,7 +325,7 @@ export async function getStaticProps() {
       content: fileContents,
     }
   })
-  // By returning { props: posts }, the Blog component
+  // By returning { props: { posts } }, the Blog component
   // will receive `posts` as a prop at build time
   return {
     props: {
@@ -355,6 +355,8 @@ When a page with `getStaticProps` is pre-rendered at build time, in addition to
 
 This JSON file will be used in client-side routing through `next/link` ([documentation](/docs/api-reference/next/link.md)) or `next/router` ([documentation](/docs/api-reference/next/router.md)). When you navigate to a page that’s pre-rendered using `getStaticProps`, Next.js fetches this JSON file (pre-computed at build time) and uses it as the props for the page component. This means that client-side page transitions will **not** call `getStaticProps` as only the exported JSON is used.
 
+When using Incremental Static Generation `getStaticProps` will be executed out of band to generate the JSON needed for client-side navigation. You may see this in the form of multiple requests being made for the same page, however, this is intended and has no impact on end-user performance
+
 #### Only allowed in a page
 
 `getStaticProps` can only be exported from a **page**. You can’t export it from non-page files.

docs/basic-features/environment-variables.md

@@ -135,3 +135,15 @@ This one is useful when running tests with tools like `jest` or `cypress` where
 There is a small difference between `test` environment, and both `development` and `production` that you need to bear in mind: `.env.local` won't be loaded, as you expect tests to produce the same results for everyone. This way every test execution will use same env defaults across different executions by ignoring your `.env.local` (which is intended to override the default set).
 
 > **Note**: similar to Default Environment Variables, `.env.test` file should be included in your repository, but `.env.test.local` shouldn't, as `.env*.local` are intended to be ignored through `.gitignore`.
+
+While running unit tests you can make sure to load your environment variables the same way Next.js does by leveraging the `loadEnvConfig` function from the `@next/env` package.
+
+```js
+// The below can be used in a Jest global setup file or similar for your testing set-up
+import { loadEnvConfig } from '@next/env'
+
+export default async () => {
+  const projectDir = process.cwd()
+  loadEnvConfig(projectDir)
+}
+```

docs/basic-features/image-optimization.md

@@ -92,6 +92,8 @@ The following Image Optimization cloud providers are included:
 
 If you need a different provider, you can use the [`loader`](/docs/api-reference/next/image.md#loader) prop with `next/image`.
 
+> The `next/image` component's default loader is not supported when using [`next export`](/docs/advanced-features/static-html-export.md). However, other loader options will work.
+
 ## Caching
 
 The following describes the caching algorithm for the default [loader](#loader). For all other loaders, please refer to your cloud provider's documentation.

docs/basic-features/pages.md

@@ -160,7 +160,9 @@ export async function getStaticPaths() {
   const posts = await res.json()
 
   // Get the paths we want to pre-render based on posts
-  const paths = posts.map((post) => `/posts/${post.id}`)
+  const paths = posts.map((post) => ({
+    params: { id: post.id },
+  }))
 
   // We'll pre-render only these paths at build time.
   // { fallback: false } means other routes should 404.

errors/export-image-api.md

@@ -11,8 +11,9 @@ This is because Next.js optimizes images on-demand, as users request them (not a
 #### Possible Ways to Fix It
 
 - Use `next start` to run a server, which includes the Image Optimization API.
-- Use Vercel to deploy, which supports [Image Optimization](https://vercel.com/docs/next.js/image-optimization).
+- Use any provider which supports Image Optimization (like [Vercel](https://vercel.com/docs/next.js/image-optimization)).
 - Configure a third-party [loader](https://nextjs.org/docs/basic-features/image-optimization#loader) in `next.config.js`.
+- Use the [`loader`](https://nextjs.org/docs/api-reference/next/image#loader) prop for `next/image`.
 
 ### Useful Links
 

examples/api-routes-apollo-server-and-client/README.md

@@ -4,6 +4,12 @@
 
 In this simple example, we integrate Apollo seamlessly with [Next.js data fetching methods](https://nextjs.org/docs/basic-features/data-fetching) to fetch queries in the server and hydrate them in the browser.
 
+## 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/api-routes-apollo-server-and-client&project-name=api-routes-apollo-server-and-client&repository-name=api-routes-apollo-server-and-client)
+
 ## 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:

examples/cms-strapi/README.md

@@ -43,7 +43,7 @@ yarn create next-app --example cms-strapi cms-strapi-app
 
 ### Step 1. Set up Strapi locally
 
-[Follow the instructions on this page](https://strapi.io/documentation/v3.x/installation/cli.html) to create a Strapi project locally.
+[Follow the instructions on this page](https://strapi.io/documentation/developer-docs/latest/getting-started/quick-start.html#_1-install-strapi-and-create-a-new-project) to create a Strapi project locally.
 
 ```bash
 npx create-strapi-app my-project --quickstart

examples/styled-jsx-with-csp/.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/styled-jsx-with-csp/README.md

@@ -0,0 +1,27 @@
+# Styled-JSX with Content Security Policy
+
+This example showcases how you can use `nonce` for `style-src` directive in `Content Security Policy` with `styled-jsx`.
+
+Checkout the [demo](https://styled-jsx-with-csp.vercel.app/) and notice the following,
+
+- `style-src` directive in `Content-Security-Policy` response header.
+- `meta` tag to pass on the `nonce` to styled-jsx for client-side rendering.
+- `style` tags with `nonce` attributes.
+
+## 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/styled-jsx-with-csp&project-name=styled-jsx-with-csp&repository-name=styled-jsx-with-csp)
+
+## 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 styled-jsx-with-csp styled-jsx-with-csp-app
+# or
+yarn create next-app --example styled-jsx-with-csp styled-jsx-with-csp-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)).