Merge remote-tracking branch 'origin/canary' into fix-image-preload-tag

vercel · Aug 31, 2020 · 2a22432 · 2a22432
2 parents b3cc250 + f1c4cb8
commit 2a22432
Show file tree

Hide file tree

Showing 756 changed files with 7,341 additions and 5,251 deletions.
diff --git a/check-examples.sh b/check-examples.sh
@@ -0,0 +1,16 @@
+#!/bin/bash
+
+cd `dirname $0`
+
+for folder in examples/* ; do
+  cp -n packages/create-next-app/templates/default/gitignore $folder/.gitignore;
+  if [ -f "$folder/package.json" ]; then
+    cat $folder/package.json | jq '.license = "MIT"' | sponge $folder/package.json
+  fi
+done;
+
+if [[ ! -z $(git status -s) ]];then
+  echo "Detected changes"
+  git status
+  exit 1
+fi
diff --git a/check-git-ignore.sh b/check-git-ignore.sh
diff --git a/contributing.md b/contributing.md
@@ -138,8 +138,6 @@ Deploy the example using [Vercel](https://vercel.com/now):
 
 ## How to use
 
-### Using `create-next-app`
-
 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
@@ -148,24 +146,5 @@ npx create-next-app --example DIRECTORY_NAME DIRECTORY_NAME-app
 yarn create next-app --example DIRECTORY_NAME DIRECTORY_NAME-app
 ```
 
-### Download manually
-
-Download the example:
-
-```bash
-curl https://codeload.github.com/vercel/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/DIRECTORY_NAME
-cd DIRECTORY_NAME
-```
-
-Install it and run:
-
-```bash
-npm install
-npm run dev
-# or
-yarn
-yarn dev
-```
-
 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)).
 ````
diff --git a/docs/advanced-features/custom-app.md b/docs/advanced-features/custom-app.md
@@ -10,7 +10,7 @@ Next.js uses the `App` component to initialize pages. You can override it and co
 - Keeping state when navigating pages
 - Custom error handling using `componentDidCatch`
 - Inject additional data into pages
-- [Add global CSS](/docs/basic-features/built-in-css-support#adding-a-global-stylesheet)
+- [Add global CSS](/docs/basic-features/built-in-css-support.md#adding-a-global-stylesheet)
 
 To override the default `App`, create the file `./pages/_app.js` as shown below:
 
@@ -47,7 +47,7 @@ The `Component` prop is the active `page`, so whenever you navigate between rout
 
 ### TypeScript
 
-If you’re using TypeScript, take a look at [our TypeScript documentation](/docs/basic-features/typescript#custom-app).
+If you’re using TypeScript, take a look at [our TypeScript documentation](/docs/basic-features/typescript.md#custom-app).
 
 ## Related
 

diff --git a/docs/advanced-features/custom-document.md b/docs/advanced-features/custom-document.md
@@ -43,7 +43,7 @@ Custom attributes are allowed as props, like `lang`:
 <Html lang="en">
 ```
 
-The `<Head />` component used here is not the same one from [`next/head`](/docs/api-reference/next/head). The `<Head />` component used here should only be used for any `<head>` code that is common for all pages. For all other cases, such as `<title>` tags, we recommend using [`next/head`](/docs/api-reference/next/head) in your pages or components.
+The `<Head />` component used here is not the same one from [`next/head`](/docs/api-reference/next/head.md). The `<Head />` component used here should only be used for any `<head>` code that is common for all pages. For all other cases, such as `<title>` tags, we recommend using [`next/head`](/docs/api-reference/next/head.md) in your pages or components.
 
 The `ctx` object is equivalent to the one received in [`getInitialProps`](/docs/api-reference/data-fetching/getInitialProps.md#context-object), with one addition:
 

diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md
@@ -2,6 +2,8 @@
 description: Override and extend the built-in Error page to handle custom errors.
 ---
 
+# Custom Error Page
+
 ## 404 Page
 
 A 404 page may be accessed very often. Server-rendering an error page for every visit increases the load of the Next.js server. This can result in increased costs and slow experiences.

diff --git a/docs/advanced-features/customizing-postcss-config.md b/docs/advanced-features/customizing-postcss-config.md
@@ -13,7 +13,7 @@ description: Extend the PostCSS config and plugins added by Next.js with your ow
 
 ## Default Behavior
 
-Next.js compiles CSS for its [built-in CSS support](/docs/basic-features/built-in-css-support) using PostCSS.
+Next.js compiles CSS for its [built-in CSS support](/docs/basic-features/built-in-css-support.md) using PostCSS.
 
 Out of the box, with no configuration, Next.js compiles CSS with the following transformations:
 
@@ -51,7 +51,7 @@ You can use the [browserl.ist](https://browserl.ist/?q=%3E0.3%25%2C+not+ie+11%2C
 
 No configuration is needed to support CSS Modules. To enable CSS Modules for a file, rename the file to have the extension `.module.css`.
 
-You can learn more about [Next.js' CSS Module support here](/docs/basic-features/built-in-css-support).
+You can learn more about [Next.js' CSS Module support here](/docs/basic-features/built-in-css-support.md).
 
 ## Customizing Plugins
 

diff --git a/docs/advanced-features/debugging.md b/docs/advanced-features/debugging.md
@@ -20,7 +20,7 @@ First, start Next.js with the inspect flag:
 NODE_OPTIONS='--inspect' next dev
 ```
 
-If you're using `npm run dev` or `yarn dev` (See: [Getting Started](/docs/getting-started)) then you should update the `dev` script on your `package.json`:
+If you're using `npm run dev` or `yarn dev` (See: [Getting Started](/docs/getting-started.md)) then you should update the `dev` script on your `package.json`:
 
 ```json
 "dev": "NODE_OPTIONS='--inspect' next dev"

diff --git a/docs/advanced-features/measuring-performance.md b/docs/advanced-features/measuring-performance.md
@@ -158,7 +158,9 @@ export function reportWebVitals(metric) {
 >
 > ```js
 > export function reportWebVitals({ id, name, label, value }) {
->   ga('send', 'event', {
+>   // Use `window.gtag` if you initialized Google Analytics as this example:
+>   // https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics/pages/_document.js
+>   window.gtag('send', 'event', {
 >     eventCategory:
 >       label === 'web-vital' ? 'Web Vitals' : 'Next.js custom metric',
 >     eventAction: name,

diff --git a/docs/advanced-features/module-path-aliases.md b/docs/advanced-features/module-path-aliases.md
@@ -4,7 +4,7 @@ description: Configure module path aliases that allow you to remap certain impor
 
 # Absolute Imports and Module path aliases
 
-Next.js automatically supports the `tsconfig.json` and `jsconfig.json` `"paths"` and `"baseUrl"` options.
+Next.js automatically supports the `tsconfig.json` and `jsconfig.json` `"paths"` and `"baseUrl"` options since [Next.js 9.4](https://nextjs.org/blog/next-9-4).
 
 > Note: `jsconfig.json` can be used when you don't use TypeScript
 

diff --git a/docs/advanced-features/preview-mode.md b/docs/advanced-features/preview-mode.md
@@ -203,6 +203,18 @@ You can pass an object to `setPreviewData` and have it be available in `getStati
 
 The preview mode works on `getServerSideProps` as well. It will also be available on the `context` object containing `preview` and `previewData`.
 
+### Works with API Routes
+
+API Routes will have access to `preview` and `previewData` under the request object. For example:
+
+```js
+export default function myApiRoute(req, res) {
+  const isPreview = req.preview
+  const previewData = req.previewData
+  // ...
+}
+```
+
 ### Unique per `next build`
 
 Both the bypass cookie value and the private key for encrypting the `previewData` change when `next build` is completed.

diff --git a/docs/advanced-features/static-html-export.md b/docs/advanced-features/static-html-export.md
@@ -21,7 +21,7 @@ The exported app supports almost every feature of Next.js, including dynamic rou
 >
 > If you're looking to make a hybrid site where only _some_ pages are prerendered to static HTML, Next.js already does that automatically for you! Read up on [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) for details.
 >
-> `next export` also causes features like Incremental Static Generation and Regeneration to be disabled, as they require `next start` or a serverless deployment to function.
+> `next export` also causes features like [Incremental Static Generation](/docs/basic-features/data-fetching.md#fallback-true) and [Regeneration](/docs/basic-features/data-fetching.md#incremental-static-regeneration) to be disabled, as they require [`next start`](/docs/api-reference/cli.md#production) or a serverless deployment to function.
 
 ## How to use it
 
@@ -53,7 +53,9 @@ For more advanced scenarios, you can define a parameter called [`exportPathMap`]
 
 ## Deployment
 
-You can read about deploying your Next.js application in the [deployment section](/docs/deployment.md).
+By default, `next export` will generate an `out` directory, which can be served by any static hosting service or CDN.
+
+> We strongly recommend using [Vercel](https://vercel.com/) even if your Next.js app is fully static. [Vercel](https://vercel.com/) is optimized to make static Next.js apps blazingly fast. `next export` works with Zero Config deployments on Vercel.
 
 ## Caveats
 
@@ -62,11 +64,10 @@ You can read about deploying your Next.js application in the [deployment section
   - `getInitialProps` cannot be used alongside `getStaticProps` or `getStaticPaths` on any given page. If you have dynamic routes, instead of using `getStaticPaths` you'll need to configure the [`exportPathMap`](/docs/api-reference/next.config.js/exportPathMap.md) parameter in your [`next.config.js`](/docs/api-reference/next.config.js/introduction.md) file to let the exporter know which HTML files it should output.
   - When `getInitialProps` is called during export, the `req` and `res` fields of its [`context`](/docs/api-reference/data-fetching/getInitialProps.md#context-object) parameter will be empty objects, since during export there is no server running.
   - `getInitialProps` **will be called on every client-side navigation**, if you'd like to only fetch data at build-time, switch to `getStaticProps`.
-  - `getInitialProps` cannot use Node.js-specific libraries or the file system like `getStaticProps` can. `getInitialProps` must fetch from an API.
+  - `getInitialProps` should fetch from an API and cannot use Node.js-specific libraries or the file system like `getStaticProps` can.
 
-  For static export, the `getStaticProps` API is always preferred over `getInitialProps`: it's recommended you convert your pages to use the `getStaticProps` if possible.
+  It's recommended to use and migrate towards `getStaticProps` over `getInitialProps` whenever possible.
 
-- The `fallback: true` mode of `getStaticPaths` is not supported when using `next export`.
-- You won't be able to render HTML dynamically when static exporting, as the HTML files are pre-build. Your application can be a hybrid of [Static Generation](/docs/basic-features/pages.md#static-generation) and [Server-Side Rendering](/docs/basic-features/pages.md#server-side-rendering) when you don't use `next export`. You can learn more about it in the [pages section](/docs/basic-features/pages.md).
+- The [`fallback: true`](/docs/basic-features/data-fetching.md#fallback-true) mode of `getStaticPaths` is not supported when using `next export`.
 - [API Routes](/docs/api-routes/introduction.md) are not supported by this method because they can't be prerendered to HTML.
 - [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering) cannot be used within pages because the method requires a server. Consider using [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) instead.
diff --git a/docs/api-reference/cli.md b/docs/api-reference/cli.md
@@ -48,14 +48,22 @@ NODE_OPTIONS='--inspect' next
 
 The first load is colored green, yellow, or red. Aim for green for performant applications.
 
-You can enable production profiling for React with the `--profile` flag in `next build`. This requires Next.js 9.5:
+You can enable production profiling for React with the `--profile` flag in `next build`. This requires [Next.js 9.5](https://nextjs.org/blog/next-9-5):
 
 ```bash
 next build --profile
 ```
 
 After that, you can use the profiler in the same way as you would in development.
 
+You can enable more verbose build output with the `--debug` flag in `next build`. This requires Next.js 9.5.3:
+
+```bash
+next build --debug
+```
+
+With this flag enabled additional build output like rewrites, redirects, and headers will be shown.
+
 ## Development
 
 `next dev` starts the application in development mode with hot-code reloading, error reporting, and more:

diff --git a/docs/api-reference/data-fetching/getInitialProps.md b/docs/api-reference/data-fetching/getInitialProps.md
@@ -4,19 +4,11 @@ description: Enable Server-Side Rendering in a page and do initial data populati
 
 # getInitialProps
 
-> **Recommended: [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) or [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering)**
+> **Recommended: [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) or [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering)**.
 >
 > If you're using Next.js 9.3 or newer, we recommend that you use `getStaticProps` or `getServerSideProps` instead of `getInitialProps`.
 >
-> These new data fetching methods allow you to have a granular choice between static generation and server-side rendering.
-> Learn more on the documentation for [Pages](/docs/basic-features/pages.md) and [Data fetching](/docs/basic-features/data-fetching.md):
-
-<details>
-  <summary><b>Examples</b></summary>
-  <ul>
-    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/data-fetch">Data fetch</a></li>
-  </ul>
-</details>
+> These new data fetching methods allow you to have a granular choice between static generation and server-side rendering. Learn more on the documentation for [Pages](/docs/basic-features/pages.md) and [Data fetching](/docs/basic-features/data-fetching.md).
 
 `getInitialProps` enables [server-side rendering](/docs/basic-features/pages.md#server-side-rendering) in a page and allows you to do **initial data population**, it means sending the [page](/docs/basic-features/pages.md) with the data already populated from the server. This is especially useful for [SEO](https://en.wikipedia.org/wiki/Search_engine_optimization).
 
@@ -71,8 +63,8 @@ For the initial page load, `getInitialProps` will run on the server only. `getIn
 - `pathname` - Current route. That is the path of the page in `/pages`
 - `query` - Query string section of URL parsed as an object
 - `asPath` - `String` of the actual path (including the query) shown in the browser
-- `req` - HTTP request object (server only)
-- `res` - HTTP response object (server only)
+- `req` - [HTTP request object](https://nodejs.org/api/http.html#http_class_http_incomingmessage 'Class: http.IncomingMessage HTTP | Node.js v14.8.0 Documentation') (server only)
+- `res` - [HTTP response object](https://nodejs.org/api/http.html#http_class_http_serverresponse 'Class: http.ServerResponse HTTP | Node.js v14.8.0 Documentation') (server only)
 - `err` - Error object if any error is encountered during the rendering
 
 ## Caveats

diff --git a/docs/api-reference/next.config.js/custom-webpack-config.md b/docs/api-reference/next.config.js/custom-webpack-config.md
@@ -6,12 +6,12 @@ description: Extend the default webpack config added by Next.js.
 
 Before continuing to add custom webpack configuration to your application make sure Next.js doesn't already support your use-case:
 
-- [CSS imports](/docs/basic-features/built-in-css-support#adding-a-global-stylesheet)
-- [CSS modules](/docs/basic-features/built-in-css-support#adding-component-level-css)
-- [Sass/SCSS imports](/docs/basic-features/built-in-css-support#sass-support)
-- [Sass/SCSS modules](/docs/basic-features/built-in-css-support#sass-support)
+- [CSS imports](/docs/basic-features/built-in-css-support.md#adding-a-global-stylesheet)
+- [CSS modules](/docs/basic-features/built-in-css-support.md#adding-component-level-css)
+- [Sass/SCSS imports](/docs/basic-features/built-in-css-support.md#sass-support)
+- [Sass/SCSS modules](/docs/basic-features/built-in-css-support.md#sass-support)
 - [preact](https://github.com/vercel/next.js/tree/canary/examples/using-preact)
-- [Customizing babel configuration](/docs/advanced-features/customizing-babel-config)
+- [Customizing babel configuration](/docs/advanced-features/customizing-babel-config.md)
 
 Some commonly asked for features are available as plugins:
 

diff --git a/docs/api-reference/next.config.js/environment-variables.md b/docs/api-reference/next.config.js/environment-variables.md
@@ -4,7 +4,7 @@ description: Learn to add and access environment variables in your Next.js appli
 
 # Environment Variables
 
-> Since the release of Next.js 9.4 we now have a more intuitive and ergonomic experience for [adding environment variables](/docs/basic-features/environment-variables.md). Give it a try!
+> Since the release of [Next.js 9.4](https://nextjs.org/blog/next-9-4) we now have a more intuitive and ergonomic experience for [adding environment variables](/docs/basic-features/environment-variables.md). Give it a try!
 
 <details>
   <summary><b>Examples</b></summary>

diff --git a/docs/api-reference/next/link.md b/docs/api-reference/next/link.md
@@ -8,6 +8,7 @@ description: Enable client-side transitions between routes with the built-in Lin
   <summary><b>Examples</b></summary>
   <ul>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/hello-world">Hello World</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/active-class-name">Active className on Link</a></li>
   </ul>
 </details>
 
@@ -45,7 +46,7 @@ export default Home
 - `href` - The path inside `pages` directory. This is the only required prop
 - `as` - The path that will be rendered in the browser URL bar. Used for dynamic routes
 - [`passHref`](#if-the-child-is-a-custom-component-that-wraps-an-a-tag) - Forces `Link` to send the `href` property to its child. Defaults to `false`
-- `prefetch` - Prefetch the page in the background. Defaults to `true`. Any `<Link />` that is in the viewport (initially or through scroll) will be preloaded. Pages using [Static Generation](/docs/basic-features/data-fetching#getstaticprops-static-generation) will preload `JSON` files with the data for faster page transitions.
+- `prefetch` - Prefetch the page in the background. Defaults to `true`. Any `<Link />` that is in the viewport (initially or through scroll) will be preloaded. Pages using [Static Generation](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) will preload `JSON` files with the data for faster page transitions.
 - [`replace`](#replace-the-url-instead-of-push) - Replace the current `history` state instead of adding a new url into the stack. Defaults to `false`
 - [`scroll`](#disable-scrolling-to-the-top-of-the-page) - Scroll to the top of the page after a 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`

diff --git a/docs/api-reference/next/router.md b/docs/api-reference/next/router.md
@@ -182,7 +182,7 @@ router.prefetch(url, as)
 ```
 
 - `url` - The path to a `page` inside the `pages` directory
-- `as` - Optional decorator for `url`, used to prefetch [dynamic routes](/docs/routing/dynamic-routes). Defaults to `url`
+- `as` - Optional decorator for `url`, used to prefetch [dynamic routes](/docs/routing/dynamic-routes.md). Defaults to `url`
 
 #### Usage
 

diff --git a/docs/api-routes/dynamic-api-routes.md b/docs/api-routes/dynamic-api-routes.md
@@ -31,7 +31,7 @@ Now, a request to `/api/post/abc` will respond with the text: `Post: abc`.
 
 A very common RESTful pattern is to set up routes like this:
 
-- `GET api/posts/` - gets a list of posts, probably paginated
+- `GET api/posts` - gets a list of posts, probably paginated
 - `GET api/posts/12345` - gets post id 12345
 
 We can model this in two ways:
@@ -40,11 +40,10 @@ We can model this in two ways:
   - `/api/posts.js`
   - `/api/posts/[postId].js`
 - Option 2:
-
   - `/api/posts/index.js`
   - `/api/posts/[postId].js`
 
-Both are equivalent. A third option of only using `/api/posts/[postId].js` is not valid because Dynamic Routes (including Catch-all routes - see below) do not have an `undefined` state and `GET api/posts/` will not match `/api/posts/[postId].js` under any circumstances.
+Both are equivalent. A third option of only using `/api/posts/[postId].js` is not valid because Dynamic Routes (including Catch-all routes - see below) do not have an `undefined` state and `GET api/posts` will not match `/api/posts/[postId].js` under any circumstances.
 
 ### Catch all API routes