Merge remote-tracking branch 'upstream/canary' into warn/auto-export-…

…query

contributing.md

@@ -12,11 +12,13 @@ Our Commitment to Open Source can be found [here](https://zeit.co/blog/oss)
 
 > You may need to run `yarn types` again if your types get outdated.
 
+To contribute to [our examples](examples), take a look at the [“Adding examples” section](#adding-examples).
+
 ## To run tests
 
 Make sure you have `chromedriver` installed for your Chrome version. You can install it with
 
-- `brew install chromedriver` on Mac OS X
+- `brew cask install chromedriver` on Mac OS X
 - `chocolatey install chromedriver` on Windows
 - Or manually downloading it from the [chromedriver repo](https://chromedriver.storage.googleapis.com/index.html) and adding the binary to `<next-repo>/node_modules/.bin`
 
@@ -112,3 +114,62 @@ EXAMPLE=./test/integration/basic
    ```sh
    yarn install --force
    ```
+
+## Adding examples
+
+When you add an example to the [examples](examples) directory, don’t forget to add a `README.md` file with the following format:
+
+- Replace `DIRECTORY_NAME` with the directory name you’re adding.
+- Fill in `Example Name` and `Description`.
+- To add additional installation instructions, please add it where appropriate.
+- To add additional notes, add `## Notes` section at the end.
+- Remove the `Deploy your own` section if your example can’t be immediately deployed to ZEIT Now.
+
+````markdown
+# Example Name
+
+Description
+
+## Deploy your own
+
+Deploy the example using [ZEIT Now](https://zeit.co/now):
+
+[![Deploy with ZEIT Now](https://zeit.co/button)](https://zeit.co/new/project?template=https://github.com/zeit/next.js/tree/canary/examples/DIRECTORY_NAME)
+
+## How to use
+
+### Using `create-next-app`
+
+Execute [`create-next-app`](https://github.com/zeit/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 DIRECTORY_NAME DIRECTORY_NAME-app
+# or
+yarn create next-app --example DIRECTORY_NAME DIRECTORY_NAME-app
+```
+
+### Download manually
+
+Download the example:
+
+```bash
+curl https://codeload.github.com/zeit/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 [now](https://zeit.co/now) ([download](https://zeit.co/download)):
+
+```bash
+now
+```
+````

docs/advanced-features/amp-support/adding-amp-components.md

@@ -1,3 +1,7 @@
+---
+description: Add components from the AMP community to AMP pages, and make your pages more interactive.
+---
+
 # Adding AMP Components
 
 The AMP community provide [many components](https://amp.dev/documentation/components/) to make AMP pages more interactive. You can add these components to your page by using `next/head`, as in the following example:

docs/advanced-features/amp-support/amp-in-static-html-export.md

@@ -1,3 +1,7 @@
+---
+description: Learn how AMP pages are created when used together with `next export`.
+---
+
 # AMP in Static HTML export
 
 When using `next export` to do [Static HTML export](/docs/advanced-features/static-html-export.md) statically prerender pages, Next.js will detect if the page supports AMP and change the exporting behavior based on that.

docs/advanced-features/amp-support/amp-validation.md

@@ -1,3 +1,7 @@
+---
+description: AMP pages are automatically validated by Next.js during development and on build. Learn more about it here.
+---
+
 # AMP Validation
 
 AMP pages are automatically validated with [amphtml-validator](https://www.npmjs.com/package/amphtml-validator) during development. Errors and warnings will appear in the terminal where you started Next.js.

docs/advanced-features/amp-support/introduction.md

@@ -1,3 +1,7 @@
+---
+description: With minimal config, and without leaving React, you can start adding AMP and improve the performance and speed of your pages.
+---
+
 # AMP Support
 
 <details>

docs/advanced-features/amp-support/typescript.md

@@ -1,3 +1,7 @@
+---
+description: Using AMP with TypeScript? Extend your typings to allow AMP components.
+---
+
 # TypeScript
 
 AMP currently doesn't have built-in types for TypeScript, but it's in their roadmap ([#13791](https://github.com/ampproject/amphtml/issues/13791)).

docs/advanced-features/automatic-static-optimization.md

@@ -1,3 +1,7 @@
+---
+description: Next.js automatically optimizes your app to be static HTML whenever possible. Learn how it works here.
+---
+
 # Automatic Static Optimization
 
 Next.js automatically determines that a page is static (can be prerendered) if it has no blocking data requirements. This determination is made by the absence of `getInitialProps` in the page.
@@ -6,7 +10,7 @@ This feature allows Next.js to emit hybrid applications that contain **both serv
 
 > Statically generated pages are still reactive: Next.js will hydrate your application client-side to give it full interactivity.
 
-One of the main benefits this feature is that optimized pages require no server-side computation, and can be instantly streamed to the end-user from multiple CDN locations. The result is an _ultra fast_ loading experience for your users.
+One of the main benefits of this feature is that optimized pages require no server-side computation, and can be instantly streamed to the end-user from multiple CDN locations. The result is an _ultra fast_ loading experience for your users.
 
 ## How it works
 

docs/advanced-features/custom-app.md

@@ -1,3 +1,7 @@
+---
+description: Control page initialization and add a layout that persists for all pages by overriding the default App component used by Next.js.
+---
+
 # Custom `App`
 
 Next.js uses the `App` component to initialize pages. You can override it and control the page initialization. Which allows you to do amazing things like:
@@ -10,6 +14,8 @@ Next.js uses the `App` component to initialize pages. You can override it and co
 To override the default `App`, create the file `./pages/_app.js` as shown below:
 
 ```jsx
+// import App from 'next/app'
+
 function MyApp({ Component, pageProps }) {
   return <Component {...pageProps} />
 }

docs/advanced-features/custom-document.md

@@ -1,3 +1,7 @@
+---
+description: Extend the default document markup added by Next.js.
+---
+
 # Custom `Document`
 
 A custom `Document` is commonly used to augment your application's `<html>` and `<body>` tags. This is necessary because Next.js pages skip the definition of the surrounding document's markup.

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

@@ -1,3 +1,7 @@
+---
+description: Override and extend the built-in Error page to handle custom errors.
+---
+
 # Custom Error Page
 
 **404** or **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

@@ -1,3 +1,7 @@
+---
+description: Start a Next.js app programmatically using a custom server.
+---
+
 # Custom Server
 
 <details>
@@ -13,7 +17,7 @@
 
 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.
 
-> Before deciding to use a custom a custom server please keep in mind that it should only be used when the integrated router of Next.js can't meet your app requirements. A custom server will remove important performance optimizations, like **serverless functions** and **[Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).**
+> Before deciding to use a custom server please keep in mind that it should only be used when the integrated router of Next.js can't meet your app requirements. A custom server will remove important performance optimizations, like **serverless functions** and **[Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).**
 
 Take a look at the following example of a custom server:
 
@@ -71,7 +75,7 @@ const app = next({})
 
 The above `next` import is a function that receives an object with the following options:
 
-- `dev`: `Boolean` - Whether or not to launch Next.js in dev mode. Defaults `false`
+- `dev`: `Boolean` - Whether or not to launch Next.js in dev mode. Defaults to `false`
 - `dir`: `String` - Location of the Next.js project. Defaults to `'.'`
 - `quiet`: `Boolean` - Hide error messages containing server information. Defaults to `false`
 - `conf`: `object` - The same object you would use in [next.config.js](/docs/api-reference/next.config.js/introduction.md). Defaults to `{}`
@@ -82,7 +86,7 @@ The returned `app` can then be used to let Next.js handle requests as required.
 
 By default, `Next` will serve each file in the `pages` folder under a pathname matching the filename. If your project uses a custom server, this behavior may result in the same content being served from multiple paths, which can present problems with SEO and UX.
 
-To disable this behavior & prevent routing based on files in `pages`, open `next.config.js` and disable the `useFileSystemPublicRoutes` config:
+To disable this behavior and prevent routing based on files in `pages`, open `next.config.js` and disable the `useFileSystemPublicRoutes` config:
 
 ```js
 module.exports = {
@@ -93,39 +97,3 @@ module.exports = {
 > Note that `useFileSystemPublicRoutes` simply disables filename routes from SSR; client-side routing may still access those paths. When using this option, you should guard against navigation to routes you do not want programmatically.
 
 > You may also wish to configure the client-side Router to disallow client-side redirects to filename routes; for that refer to [`Router.beforePopState`](/docs/api-reference/next/router.md#router.beforePopState).
-
-## Dynamic `assetPrefix`
-
-Sometimes you may need to set the [`assetPrefix`](/docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md) dynamically. This is useful when changing the `assetPrefix` based on incoming requests.
-
-For that, you can use `app.setAssetPrefix`, as in the following example:
-
-```js
-const next = require('next')
-const http = require('http')
-
-const dev = process.env.NODE_ENV !== 'production'
-const app = next({ dev })
-const handleNextRequests = app.getRequestHandler()
-
-app.prepare().then(() => {
-  const server = new http.Server((req, res) => {
-    // Add assetPrefix support based on the hostname
-    if (req.headers.host === 'my-app.com') {
-      app.setAssetPrefix('http://cdn.com/myapp')
-    } else {
-      app.setAssetPrefix('')
-    }
-
-    handleNextRequests(req, res)
-  })
-
-  server.listen(port, err => {
-    if (err) {
-      throw err
-    }
-
-    console.log(`> Ready on http://localhost:${port}`)
-  })
-})
-```

docs/advanced-features/customizing-babel-config.md

@@ -1,3 +1,7 @@
+---
+description: Extend the babel preset added by Next.js with your own configs.
+---
+
 # Customizing Babel Config
 
 <details>

docs/advanced-features/dynamic-import.md

@@ -1,3 +1,7 @@
+---
+description: Dynamically import JavaScript modules and React Components and split your code into manageable chunks.
+---
+
 # Dynamic Import
 
 <details>

docs/advanced-features/src-directory.md

@@ -1,3 +1,7 @@
+---
+description: Save pages under the `src` directory as an alternative to the root `pages` directory.
+---
+
 # `src` Directory
 
 Pages can also be added under `src/pages` as an alternative to the root `pages` directory.

docs/advanced-features/static-html-export.md

@@ -1,3 +1,7 @@
+---
+description: Export your Next.js app to static HTML, and run it standalone without the need of a Node.js server.
+---
+
 # Static HTML Export
 
 <details>
@@ -11,9 +15,9 @@
 
 The exported app supports almost every feature of Next.js, including dynamic routes, prefetching, preloading and dynamic imports.
 
-The way `next export` works is by prerendering all pages to HTML; it does so based on a mapping mapping called [`exportPathMap`](/docs/api-reference/next.config.js/exportPathMap.md).
+The way `next export` works is by prerendering all pages to HTML; it does so based on a mapping called [`exportPathMap`](/docs/api-reference/next.config.js/exportPathMap.md).
 
-> If your pages don't have `getInitialProps` you may not need `next export` at all, `next build` is already enough thanks to [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).
+> If your pages don't have `getInitialProps` you may not need `next export` at all; `next build` is already enough thanks to [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).
 
 ## How to use it
 
@@ -49,6 +53,6 @@ You can read about deploying your Next.js application in the [deployment section
 
 ## Caveats
 
-- With `next export`, we build a HTML version of your app. At export time we will run the [`getInitialProps`](/docs/api-reference/data-fetching/getInitialProps.md) in your pages. The `req` and `res` fields of the [`context`](/docs/api-reference/data-fetching/getInitialProps.md#context-object) object will be empty objects during export as there is no server running
-- You won't be able to render HTML dynamically when static exporting, as we pre-build the HTML files. You 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).
-- [API Routes](/docs/api-routes/introduction.md) are not supported by this method because they can't be prerendered to HTML
+- With `next export`, we build an HTML version of your app. At export time we will run the [`getInitialProps`](/docs/api-reference/data-fetching/getInitialProps.md) in your pages. The `req` and `res` fields of the [`context`](/docs/api-reference/data-fetching/getInitialProps.md#context-object) object will be empty objects during export as there is no server running.
+- You won't be able to render HTML dynamically when static exporting, as we pre-build the HTML files. 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).
+- [API Routes](/docs/api-routes/introduction.md) are not supported by this method because they can't be prerendered to HTML.

docs/api-reference/cli.md

@@ -1,3 +1,7 @@
+---
+description: The Next.js CLI allows you to start, build, and export your application. Learn more about it here.
+---
+
 # Next.js CLI
 
 The Next.js CLI allows you to start, build, and export your application.

docs/api-reference/data-fetching/getInitialProps.md

@@ -1,3 +1,7 @@
+---
+description: Enable Server-Side Rendering in a page and do initial data population with `getInitialProps`.
+---
+
 # getInitialProps
 
 <details>
@@ -33,6 +37,7 @@ Or using a class component:
 
 ```jsx
 import React from 'react'
+import fetch from 'isomorphic-unfetch'
 
 class Page extends React.Component {
   static async getInitialProps(ctx) {
@@ -42,7 +47,7 @@ class Page extends React.Component {
   }
 
   render() {
-    return <div>Next stars: {stars}</div>
+    return <div>Next stars: {this.props.stars}</div>
   }
 }
 
@@ -59,8 +64,8 @@ For the initial page load, `getInitialProps` will execute on the server only. `g
 
 `getInitialProps` receives a single argument called `context`, it's an object with the following properties:
 
-- `pathname` - path section of URL
-- `query` - query string section of URL parsed as an object
+- `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)
@@ -69,7 +74,7 @@ For the initial page load, `getInitialProps` will execute on the server only. `g
 ## Caveats
 
 - `getInitialProps` can **not** be used in children components, only in the default export of every page
-- If you are using server-side only modules inside `getinitialProps`, make sure to [import them properly](https://arunoda.me/blog/ssr-and-server-only-modules), otherwise it'll slow down your app
+- If you are using server-side only modules inside `getInitialProps`, make sure to [import them properly](https://arunoda.me/blog/ssr-and-server-only-modules), otherwise it'll slow down your app
 
 ## Related
 

docs/api-reference/next.config.js/build-target.md

@@ -1,3 +1,7 @@
+---
+description: Learn more about the build targets used by Next.js, which decide the way your application is built and run.
+---
+
 # Build Target
 
 Next.js supports various build targets, each changing the way your application is built and run. We'll explain each of the targets below.

docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md

@@ -1,3 +1,7 @@
+---
+description: A custom asset prefix allows you serve static assets from a CDN. Learn more about it here.
+---
+
 # CDN Support with Asset Prefix
 
 To set up a [CDN](https://en.wikipedia.org/wiki/Content_delivery_network), you can set up an asset prefix and configure your CDN's origin to resolve to the domain that Next.js is hosted on.

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

@@ -1,3 +1,7 @@
+---
+description: Next.js provides gzip compression to compress rendered content and static files, it only works with the server target. Learn more about it here.
+---
+
 # Compression
 
 Next.js provides [**gzip**](https://tools.ietf.org/html/rfc6713#section-3) compression to compress rendered content and static files. Compression only works with the [`server` target](/docs/api-reference/next.config.js/build-target.md#server-target). In general you will want to enable compression on a HTTP proxy like [nginx](https://www.nginx.com/), to offload load from the `Node.js` process.

docs/api-reference/next.config.js/configuring-onDemandEntries.md

@@ -1,3 +1,7 @@
+---
+description: Configure how Next.js will dispose and keep in memory pages created in development.
+---
+
 # Configuring onDemandEntries
 
 Next.js exposes some options that give you some control over how the server will dispose or keep in memory built pages in development.

docs/api-reference/next.config.js/configuring-the-build-id.md

@@ -1,3 +1,7 @@
+---
+description: Configure the build id, which is used to identify the current build in which your application is being served.
+---
+
 # Configuring the Build ID
 
 Next.js uses a constant id generated at build time to identify which version of your application is being served. This can cause problems in multi-server deployments when `next build` is ran on every server. In order to keep a static build id between builds you can provide your own build id.

docs/api-reference/next.config.js/custom-page-extensions.md

@@ -1,3 +1,7 @@
+---
+description: Extend the default page extensions used by Next.js when resolving pages in the pages directory.
+---
+
 # Custom Page Extensions
 
 Aimed at modules like [@next/mdx](https://github.com/zeit/next.js/tree/canary/packages/next-mdx), which adds support for pages ending with `.mdx`. You can configure the extensions looked for in the `pages` directory when resolving pages.