Merge branch 'canary' into examples/apollo-easy-config

vercel · Feb 13, 2020 · ed94c45 · ed94c45
2 parents 565b739 + 3e7cfd1
commit ed94c45
Show file tree

Hide file tree

Showing 285 changed files with 2,654 additions and 1,758 deletions.
diff --git a/contributing.md b/contributing.md
@@ -167,9 +167,5 @@ yarn
 yarn dev
 ```
 
-Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit.co/download)):
-
-```bash
-now
-```
+Deploy it to the cloud with [ZEIT Now](https://zeit.co/new?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-document.md b/docs/advanced-features/custom-document.md
@@ -37,6 +37,12 @@ export default MyDocument
 
 `<Html>`, `<Head />`, `<Main />` and `<NextScript />` are required for the page to be properly rendered.
 
+Custom attributes are allowed as props, like `lang`:
+
+```jsx
+<Html lang="en">
+```
+
 The `ctx` object is equivalent to the one received in [`getInitialProps`](/docs/api-reference/data-fetching/getInitialProps.md#context-object), with one addition:
 
 - `renderPage`: `Function` - a callback that executes the actual React rendering logic (synchronously). It's useful to decorate this function in order to support server-rendering wrappers like Aphrodite's [`renderStatic`](https://github.com/Khan/aphrodite#server-side-rendering)

diff --git a/docs/advanced-features/dynamic-import.md b/docs/advanced-features/dynamic-import.md
@@ -17,6 +17,8 @@ You can think of dynamic imports as another way to split your code into manageab
 
 ## Basic usage
 
+In the following example, the module `../components/hello` will be dynamically loaded by the page:
+
 ```jsx
 import dynamic from 'next/dynamic'
 
@@ -35,14 +37,21 @@ function Home() {
 export default Home
 ```
 
+`DynamicComponent` will be the default component returned by `../components/hello`. It works like a regular React Component, and you can pass props to it as you normally would.
+
 ## With named exports
 
+If the dynamic component is not the default export, you can use a named export too. Consider the module `../components/hello.js` which has a named export `Hello`:
+
 ```jsx
-// components/hello.js
 export function Hello() {
   return <p>Hello!</p>
 }
+```
 
+To dynamically import the `Hello` component, you can return it from the [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) returned by [`import()`](https://github.com/tc39/proposal-dynamic-import#example), like so:
+
+```jsx
 import dynamic from 'next/dynamic'
 
 const DynamicComponent = dynamic(() =>
@@ -64,6 +73,8 @@ export default Home
 
 ## With custom loading component
 
+An optional `loading` component can be added to render a loading state while the dynamic component is being loaded. For example:
+
 ```jsx
 import dynamic from 'next/dynamic'
 

diff --git a/docs/api-reference/next.config.js/build-target.md b/docs/api-reference/next.config.js/build-target.md
@@ -8,17 +8,19 @@ Next.js supports various build targets, each changing the way your application i
 
 ## `server` target
 
-> This is the default target, however, we highly recommend the [`serverless` target](#serverless-target). The `serverless` target enforces additional constraints to keep you in the [Pit of Success](https://blog.codinghorror.com/falling-into-the-pit-of-success/).
+> This is the default target, however, we highly recommend the [`serverless` target](#serverless-target). The `serverless` target enforces [additional constraints](https://rauchg.com/2020/2019-in-review#serverless-upgrades-itself) to keep you in the [Pit of Success](https://blog.codinghorror.com/falling-into-the-pit-of-success/).
 
 This target is compatible with both `next start` and [custom server](/docs/advanced-features/custom-server.md) setups (it's mandatory for a custom server).
 
 Your application will be built and deployed as a monolith. This is the default target and no action is required on your part to opt-in.
 
 ## `serverless` target
 
-> Deployments to [ZEIT Now](https://zeit.co/home) will automatically enable this target. You do not need to opt-into it yourself, but you can.
+> Deployments to [ZEIT Now](https://zeit.co) will automatically enable this target. You do not need to opt-into it yourself, but you can.
 
-This target will output each page in a self-contained Serverless Function. It's only compatible with `next start` or Serverless deployment platforms (like ZEIT Now) — you cannot use the custom server API.
+This target will output independent pages that don't require a monolithic server.
+
+It's only compatible with `next start` or Serverless deployment platforms (like [ZEIT Now](https://zeit.co)) — you cannot use the custom server API.
 
 To opt-into this target, set the following configuration in your `next.config.js`:
 

diff --git a/docs/api-reference/next.config.js/ignoring-typescript-errors.md b/docs/api-reference/next.config.js/ignoring-typescript-errors.md
@@ -24,7 +24,7 @@ If you'd like Next.js to dangerously produce production code even when your appl
 
 > Be sure you are running type checks as part of your build or deploy process, otherwise this can be very dangerous.
 
-Open `next.config.js` and enable the `ignoreDevErrors` option in the `typescript` config:
+Open `next.config.js` and enable the `ignoreBuildErrors` option in the `typescript` config:
 
 ```js
 module.exports = {

diff --git a/docs/api-reference/next/link.md b/docs/api-reference/next/link.md
@@ -99,7 +99,7 @@ function NavLink({ href, name }) {
 export default NavLink
 ```
 
-> **Note:** If you’re using [emotion](https://emotion.sh/)’s JSX pragma feature (`@jsx jsx`), you must use `passHref` even if you use an `<a>` tag directly.
+> **Note**: If you’re using [emotion](https://emotion.sh/)’s JSX pragma feature (`@jsx jsx`), you must use `passHref` even if you use an `<a>` tag directly.
 
 ## If the child is a function component
 

diff --git a/docs/api-routes/dynamic-api-routes.md b/docs/api-routes/dynamic-api-routes.md
@@ -19,3 +19,44 @@ export default (req, res) => {
 ```
 
 Now, a request to `/api/post/abc` will respond with the text: `Post: abc`.
+
+### Catch all API routes
+
+API Routes can be extended to catch all paths by adding three dots (`...`) inside the brackets. For example:
+
+- `pages/api/post/[...slug].js` matches `/api/post/a`, but also `/api/post/a/b`, `/api/post/a/b/c` and so on.
+
+> **Note**: You can use names other than `slug`, such as: `[...param]`
+
+Matched parameters will be sent as a query parameter (`slug` in the example) to the page, and it will always be an array, so, the path `/api/post/a` will have the following `query` object:
+
+```json
+{ "slug": ["a"] }
+```
+
+And in the case of `/api/post/a/b`, and any other matching path, new parameters will be added to the array, like so:
+
+```json
+{ "slug": ["a", "b"] }
+```
+
+An API route for `pages/api/post/[...slug].js` could look like this:
+
+```js
+export default (req, res) => {
+  const {
+    query: { slug },
+  } = req
+
+  res.end(`Post: ${slug.join(', ')}`)
+}
+```
+
+Now, a request to `/api/post/a/b/c` will respond with the text: `Post: a, b, c`.
+
+## Caveats
+
+- Predefined API routes take precedence over dynamic API routes, and dynamic API routes over catch all API routes. Take a look at the following examples:
+  - `pages/api/post/create.js` - Will match `/api/post/create`
+  - `pages/api/post/[pid].js` - Will match `/api/post/1`, `/api/post/abc`, etc. But not `/api/post/create`
+  - `pages/api/post/[...slug].js` - Will match `/api/post/1/2`, `/api/post/a/b/c`, etc. But not `/api/post/create`, `/api/post/abc`
diff --git a/docs/deployment.md b/docs/deployment.md
@@ -1,105 +1,77 @@
 ---
-description: Compile and deploy your Next.js app to production with ZEIT Now and other hosting alternatives.
+description: Deploy your Next.js app to production with ZEIT Now and other hosting options.
 ---
 
 # Deployment
 
-To go to production Next.js has a `next build` command. When run, it will compile your project and automatically apply numerous optimizations.
+## ZEIT Now (Recommended)
 
-## Prepare your package.json
+The easiest way to deploy Next.js to production is to use the **[ZEIT Now platform](https://zeit.co)** from the creators of Next.js. [ZEIT Now](https://zeit.co) is an all-in-one platform with Global CDN supporting static & JAMstack deployment and Serverless Functions.
 
-Ensure your `package.json` has the `"build"` and `"start"` scripts:
-
-```json
-{
-  "scripts": {
-    "dev": "next",
-    "build": "next build",
-    "start": "next start"
-  }
-}
-```
-
-In the case that you'd want to do a [full static export](/docs/advanced-features/static-html-export.md) of the Next.js application add `next export` to the `"build"` script:
-
-```json
-{
-  "scripts": {
-    "dev": "next",
-    "build": "next build && next export",
-    "start": "next start"
-  }
-}
-```
+### Getting started
 
-## ZEIT Now
+If you haven’t already done so, push your Next.js app to a Git provider of your choice: [GitHub](http://github.com/), [GitLab](https://gitlab.com/), or [BitBucket](https://bitbucket.org/). Your repository can be private or public.
 
-The easiest way to deploy Next.js to production is using the [ZEIT Now platform](https://zeit.co) from the creators of Next.js.
+Then, follow these steps:
 
-### Preview deployments
+1. [Sign up to ZEIT Now](https://zeit.co/signup) (no credit card is required).
+2. After signing up, you’ll arrive on the [“Create a new project”](https://zeit.co/new) page. Under “From your existing code”, choose the Git provider you use and set up an integration. (Instructions: [GitHub](https://zeit.co/docs/v2/git-integrations/zeit-now-for-github) / [GitLab](https://zeit.co/docs/v2/git-integrations/zeit-now-for-gitlab) / [BitBucket](https://zeit.co/docs/v2/git-integrations/zeit-now-for-bitbucket)).
+3. Once that’s set up, click “New Project From …” and import your Next.js app. It auto-detects that your app is using Next.js and sets up the build configuration for you. No need to change anything — everything just works!
+4. After importing, it’ll deploy your Next.js app and provide you with a deployment URL. Click “Visit” to see your app in production.
 
-ZEIT Now integrates directly with GitHub, GitLab, and Bitbucket to give you a unique shareable url for every commit and every pull request. This url can be shared with customers and can be used to run integration tests against.
+Congratulations! You’ve just deployed your Next.js app! If you have questions, take a look at the [ZEIT Now documentation](https://zeit.co/docs).
 
-### Hybrid Next.js
+> If you’re using a [custom server](/docs/advanced-features/custom-server.md), we strongly recommend migrating away from it (for example, by using [dynamic routing](/docs/routing/dynamic-routes.md)). If you cannot migrate, consider [other hosting options](#other-hosting-options).
 
-The [hybrid pages](/docs/basic-features/pages.md) approach is fully supported out of the box. Meaning that 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).
+### DPS: Develop, Preview, Ship
 
-In case of [Static Generation](/docs/basic-features/pages.md#static-generation) the page will automatically be served from the ZEIT Now Smart CDN.
+Let’s talk about the workflow we recommend using. [ZEIT Now](https://zeit.co) supports what we call the **DPS** workflow: **D**evelop, **P**review, and **S**hip:
 
-When the page is using [Server-Side Rendering](/docs/basic-features/pages.md#server-side-rendering) it will become an isolated serverless function automatically. This allows the page rendering to scale automatically and be independent—errors on one page won't affect another.
+- **Develop:** Write code in Next.js. Keep the development server running and take advantage of its hot code reloading feature.
+- **Preview:** Every time you push changes to a branch on GitHub / GitLab / BitBucket, ZEIT Now automatically creates a new deployment with a unique URL. You can view them on GitHub when you open a pull request, or under “Preview Deployments” on your project page on ZEIT Now. [Learn more about it here](https://zeit.co/features/deployment-previews).
+- **Ship:** When you’re ready to ship, merge the pull request to your default branch (e.g. `master`). ZEIT Now will automatically create a production deployment.
 
-API routes will also become separate serverless functions that execute and scale separately from each other.
+By using the DPS workflow, in addition to doing _code reviews_, you can do _deployment previews_. Each deployment creates a unique URL that can be shared or used for integration tests.
 
-### CDN + HTTPS by default
+### Optimized for Next.js
 
-Assets (JavaScript, CSS, images, fonts etc) and Statically Generated pages are automatically served through the ZEIT Now Smart CDN, ensuring these are always served close to your users.
+[ZEIT Now](https://zeit.co) is made by the creators of Next.js and has first-class support for Next.js.
 
-HTTPS is enabled by default and doesn't require extra configuration.
+For example, the [hybrid pages](/docs/basic-features/pages.md) approach is fully supported out of the box.
 
-### Getting started
+- 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 [ZEIT Now Smart CDN](https://zeit.co/smart-cdn), 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.
 
-#### From a git repository
+### Custom Domains, Environment Variables, Automatic HTTPS, and more
 
-You can link your project in [GitHub](https://zeit.co/new), [GitLab](https://zeit.co/new), or [Bitbucket](https://zeit.co/new) through the [web interface](https://zeit.co/new). This will automatically set up deployment previews for pull requests and commits. To learn more about ZEIT Now’s Git integration, take a look at [our documentation here](https://zeit.co/docs/v2/git-integration/).
+- **Custom Domains:** Once deployed on [ZEIT Now](https://zeit.co), you can assign a custom domain to your Next.js app. Take a look at [our documentation here](https://zeit.co/docs/v2/custom-domains).
+- **Environment Variables:** You can also set environment variables on ZEIT Now. Take a look at [our documentation here](https://zeit.co/docs/v2/build-step#using-environment-variables-and-secrets). You can then [use those environment variables](/docs/api-reference/next.config.js/environment-variables.md) in your Next.js app.
+- **Automatic HTTPS:** HTTPS is enabled by default (including custom domains) and doesn't require extra configuration. We auto-renew SSL certificates.
+- **More:** [Read our documentation](https://zeit.co/docs) to learn more about the ZEIT Now platform.
 
-#### Through the ZEIT Now CLI
+## Other hosting options
 
-You can install [Now CLI](https://zeit.co/download) from either npm or Yarn. Using npm, run the following command from your terminal:
+### Node.js Server
 
-```bash
-npm install -g now
-```
+Next.js can be deployed to any hosting provider that supports Node.js. This is the approach you should take if you’re using a [custom server](/docs/advanced-features/custom-server.md).
 
-You can deploy your application by running the following command in the root of the project directory:
+Make sure your `package.json` has the `"build"` and `"start"` scripts:
 
-```bash
-now
+```json
+{
+  "scripts": {
+    "dev": "next",
+    "build": "next build",
+    "start": "next start"
+  }
+}
 ```
 
-You will receive a unique link similar to the following: https://your-project.username.now.sh.
-
-#### Custom domains
-
-Once deployed on ZEIT Now, your projects can be assigned to a custom domain of your choice. To learn more, take a look at [our documentation here](https://zeit.co/docs/v2/custom-domains/).
-
-## Self hosting
-
-Next.js can be deployed to any hosting provider that supports Node.js. In order to self-host there are two commands: `next build` and `next start`.
-
-`next build` builds the production application in the `.next` folder.
-
-`next start` starts a Node.js server that supports [hybrid pages](/docs/basic-features/pages.md), serving both statically generated and server-side rendered pages.
-
-Generally you'll have to follow these steps to deploy to production:
+`next build` builds the production application in the `.next` folder. After building, `next start` starts a Node.js server that supports [hybrid pages](/docs/basic-features/pages.md), serving both statically generated and server-side rendered pages.
 
-- Run `npm install`
-- Run `npm run build` (runs `next build`)
-- Potentially copy the `.next`, `node_modules`, and `package.json` to your server.
-- Run `npm run start` (runs `next start`) on the server
+### Static HTML Export
 
-In case you're doing a full static export using `next export` the steps are slightly different and don't involve using `next start`:
+If you’d like to do a static HTML export of your Next.js app, follow the directions on [our documentation](/docs/advanced-features/static-html-export.md). By default, `next export` will generate an `out` directory, which can be served by any static hosting service or CDN.
 
-- Run `npm install`
-- Run `npm run build` (runs `next build && next export`)
-- A `out` directory is generated by `next export`
-- Copy the `out` directory to the server and make sure it's served by your server
+> We strongly recommend using [ZEIT Now](https://zeit.co/) even if your Next.js app is fully static. [ZEIT Now](https://zeit.co/) is optimized to make static Next.js apps blazingly fast. `next export` works with Zero Config deployments on ZEIT Now.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -17,6 +17,18 @@ The interactive course with quizzes will guide you through everything you need t
 
 ## Setup
 
+We recommend creating a new Next.js app using `create-next-app`, which sets up everything automatically for you. To create a project, run:
+
+```bash
+npm init next-app
+# or
+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.
+
+## Manual Setup
+
 Install `next`, `react` and `react-dom` in your project:
 
 ```bash

diff --git a/docs/routing/dynamic-routes.md b/docs/routing/dynamic-routes.md
@@ -67,15 +67,17 @@ Client-side navigations to a dynamic route can be handled with [`next/link`](/do
 
 Dynamic routes can be extended to catch all paths by adding three dots (`...`) inside the brackets. For example:
 
-- `pages/post/[...slug].js` matches `/post/a`, but also `post/a/b`, `post/a/b/c` and so on.
+- `pages/post/[...slug].js` matches `/post/a`, but also `/post/a/b`, `/post/a/b/c` and so on.
+
+> **Note**: You can use names other than `slug`, such as: `[...param]`
 
 Matched parameters will be sent as a query parameter (`slug` in the example) to the page, and it will always be an array, so, the path `/post/a` will have the following `query` object:
 
 ```json
 { "slug": ["a"] }
 ```
 
-And in the case of `post/a/b`, and any other matching path, new parameters will be added to the array, like so:
+And in the case of `/post/a/b`, and any other matching path, new parameters will be added to the array, like so:
 
 ```json
 { "slug": ["a", "b"] }
@@ -85,9 +87,10 @@ And in the case of `post/a/b`, and any other matching path, new parameters will
 
 ## Caveats
 
-- Predefined routes take precedence over dynamic routes. Take a look at the following examples:
+- Predefined routes take precedence over dynamic routes, and dynamic routes over catch all routes. Take a look at the following examples:
   - `pages/post/create.js` - Will match `/post/create`
-  - `pages/post/[pid].js` - Will match `/post/1`, `/post/abc`, etc. but not `/post/create`
+  - `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 (`{}`).
 
   After hydration, Next.js will trigger an update to your application to provide the route parameters in the `query` object.
diff --git a/examples/active-class-name/README.md b/examples/active-class-name/README.md
@@ -39,8 +39,4 @@ yarn
 yarn dev
 ```
 
-Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit.co/download)):
-
-```bash
-now
-```
+Deploy it to the cloud with [ZEIT Now](https://zeit.co/new?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).