Merge branch 'canary' into polyfillio-lint

vercel · Jul 17, 2020 · 9a2dc9a · 9a2dc9a
2 parents 432a8a7 + 5e9f310
commit 9a2dc9a
Show file tree

Hide file tree

Showing 395 changed files with 10,418 additions and 1,187 deletions.
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1 @@
+Visit https://vercel.com/security to view the disclosure policy.
diff --git a/check-git-ignore.sh b/check-git-ignore.sh
@@ -0,0 +1,13 @@
+#!/bin/bash
+
+cd `dirname $0`
+
+for folder in examples/* ;
+  do cp -n packages/create-next-app/templates/default/gitignore $folder/.gitignore;
+done;
+
+if [[ ! -z $(git status -s) ]];then
+  echo "Detected changes"
+  git status
+  exit 1
+fi
diff --git a/docs/advanced-features/custom-document.md b/docs/advanced-features/custom-document.md
@@ -6,8 +6,6 @@ description: Extend the default document markup added by Next.js.
 
 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.
 
-A custom `Document` can also include `getInitialProps` for expressing asynchronous server-rendering data requirements.
-
 To override the default `Document`, create the file `./pages/_document.js` and extend the `Document` class as shown below:
 
 ```jsx
@@ -35,6 +33,8 @@ class MyDocument extends Document {
 export default MyDocument
 ```
 
+> The code above is the default `Document` added by Next.js. Feel free to remove the `getInitialProps` or `render` function from `MyDocument` if you don't need to change them.
+
 `<Html>`, `<Head />`, `<Main />` and `<NextScript />` are required for the page to be properly rendered.
 
 Custom attributes are allowed as props, like `lang`:
@@ -43,17 +43,18 @@ 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 `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 runs 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)
 
 ## Caveats
 
 - `Document` is only rendered in the server, event handlers like `onClick` won't work
-- React components outside of `<Main />` will not be initialized by the browser. Do _not_ add application logic here. If you need shared components in all your pages (like a menu or a toolbar), take a look at the [`App`](/docs/advanced-features/custom-app.md) component instead
+- React components outside of `<Main />` will not be initialized by the browser. Do _not_ add application logic here or custom CSS (like `styled-jsx`). If you need shared components in all your pages (like a menu or a toolbar), take a look at the [`App`](/docs/advanced-features/custom-app.md) component instead
 - `Document`'s `getInitialProps` function is not called during client-side transitions, nor when a page is [statically optimized](/docs/advanced-features/automatic-static-optimization.md)
 - Make sure to check if `ctx.req` / `ctx.res` are defined in `getInitialProps`. Those variables will be `undefined` when a page is being statically exported by [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) or by [`next export`](/docs/advanced-features/static-html-export.md)
-- Common errors include adding a `<title>` in the `<Head />` tag or using `styled-jsx`. These should be avoided in `pages/_document.js` as they lead to unexpected behavior
 
 ## Customizing `renderPage`
 

diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md
@@ -75,3 +75,5 @@ export default function Page({ errorCode, stars }) {
 ```
 
 The `Error` component also takes `title` as a property if you want to pass in a text message along with a `statusCode`.
+
+If you have a custom `Error` component be sure to import that one instead. `next/error` exports the default component used by Next.js.
diff --git a/docs/advanced-features/debugging.md b/docs/advanced-features/debugging.md
@@ -40,7 +40,7 @@ ready - started server on http://localhost:3000
 
 ### Using Chrome DevTools
 
-Once you open a new tab in Google Chrome and go to `chrome://inspect`, you should see your Next.js application inside the "Remote Target" section. Now click "inspect" to open a screen that will be your debugging environement from now on.
+Once you open a new tab in Google Chrome and go to `chrome://inspect`, you should see your Next.js application inside the "Remote Target" section. Now click "inspect" to open a screen that will be your debugging environment from now on.
 
 ### Using the Debugger in Visual Studio Code
 
@@ -71,7 +71,7 @@ Now you can use the [`debugger`](https://developer.mozilla.org/en-US/docs/Web/Ja
 
 If you trigger the underlying code by refreshing the current page, clicking on a page link or fetching an API route, your code will be paused and the debugger window will pop up.
 
-To learn more on how to use a JavaScript debugger, take a look the following documentation:
+To learn more on how to use a JavaScript debugger, take a look at the following documentation:
 
 - [VS Code Node.js debugging: Breakpoints](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_breakpoints)
 - [Get Started with Debugging JavaScript in Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools/javascript)
diff --git a/docs/api-reference/next.config.js/headers.md b/docs/api-reference/next.config.js/headers.md
@@ -89,3 +89,37 @@ module.exports = {
   },
 }
 ```
+
+### 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:
+
+```js
+module.exports = {
+  basePath: '/docs',
+
+  async headers() {
+    return [
+      {
+        source: '/with-basePath', // becomes /docs/with-basePath
+        headers: [
+          {
+            key: 'x-hello',
+            value: 'world'
+          }
+        ]
+      },
+      {
+        source: '/without-basePath', // is not modified since basePath: false is set
+        headers: [
+          {
+            key: 'x-hello',
+            value: 'world'
+          }
+        ]
+        basePath: false
+      },
+    ]
+  },
+}
+```
diff --git a/docs/api-reference/next.config.js/redirects.md b/docs/api-reference/next.config.js/redirects.md
@@ -65,3 +65,30 @@ module.exports = {
   },
 }
 ```
+
+### 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:
+
+```js
+module.exports = {
+  basePath: '/docs',
+
+  async redirects() {
+    return [
+      {
+        source: '/with-basePath', // automatically becomes /docs/with-basePath
+        destination: '/another', // automatically becomes /docs/another
+        permanent: false,
+      },
+      {
+        // does not add /docs since basePath: false is set
+        source: '/without-basePath',
+        destination: '/another',
+        basePath: false,
+        permanent: false,
+      },
+    ]
+  },
+}
+```
diff --git a/docs/api-reference/next.config.js/rewrites.md b/docs/api-reference/next.config.js/rewrites.md
@@ -110,3 +110,28 @@ module.exports = {
   },
 }
 ```
+
+### Rewrites with basePath support
+
+When leveraging [`basePath` support](/docs/api-reference/next.config.js/basepath.md) with rewrites each `source` and `destination` is automatically prefixed with the `basePath` unless you add `basePath: false` to the rewrite:
+
+```js
+module.exports = {
+  basePath: '/docs',
+
+  async rewrites() {
+    return [
+      {
+        source: '/with-basePath', // automatically becomes /docs/with-basePath
+        destination: '/another', // automatically becomes /docs/another
+      },
+      {
+        // does not add /docs since basePath: false is set
+        source: '/without-basePath',
+        destination: '/another',
+        basePath: false,
+      },
+    ]
+  },
+}
+```
diff --git a/docs/api-routes/api-middlewares.md b/docs/api-routes/api-middlewares.md
@@ -116,3 +116,76 @@ export default handler
 ```
 
 > Go to the [API Routes with CORS](https://github.com/vercel/next.js/tree/canary/examples/api-routes-cors) example to see the finished app
+
+## Extending the `req`/`res` objects with TypeScript
+
+For better type-safety, it is not recommended to extend the `req` and `res` objects. Instead, use pure functions to work with them:
+
+```ts
+// utils/cookies.ts
+
+import { serialize } from 'cookie'
+import { NextApiResponse } from 'next'
+
+/**
+ * This sets `cookie` using the `res` object
+ */
+
+type Options = {
+  expires?: Date
+  maxAge?: number
+}
+
+export const setCookie = (
+  res: NextApiResponse,
+  name: string,
+  value: unknown,
+  options: Options = {}
+) => {
+  const stringValue =
+    typeof value === 'object' ? 'j:' + JSON.stringify(value) : String(value)
+
+  if ('maxAge' in options) {
+    options.expires = new Date(Date.now() + options.maxAge)
+    options.maxAge /= 1000
+  }
+
+  res.setHeader('Set-Cookie', serialize(name, String(stringValue), options))
+}
+
+// pages/api/cookies.ts
+
+import { NextApiRequest, NextApiResponse } from 'next'
+import { setCookie } from '../../utils/cookies'
+
+const handler = (req: NextApiRequest, res: NextApiResponse) => {
+  // Calling our pure function using the `res` object, it will add the `set-cookie` header
+  setCookie(res, 'Next.js', 'api-middleware!')
+  // Return the `set-cookie` header so we can display it in the browser and show that it works!
+  res.end(res.getHeader('Set-Cookie'))
+}
+
+export default handler
+```
+
+If you can't avoid these objects from being extended, you have to create your own type to include the extra properties:
+
+```ts
+// pages/api/foo.ts
+
+import { NextApiRequest, NextApiResponse } from 'next'
+import { withFoo } from 'external-lib-foo'
+
+type NextApiRequestWithFoo = NextApiRequest & {
+  foo: (bar: string) => void
+}
+
+const handler = (req: NextApiRequestWithFoo, res: NextApiResponse) => {
+  req.foo('bar') // we can now use `req.foo` without type errors
+  res.end('ok')
+}
+
+export default withFoo(handler)
+```
+
+Keep in mind this is not safe since the code will still compile even if you remove `withFoo()` from the export.
diff --git a/docs/basic-features/environment-variables.md b/docs/basic-features/environment-variables.md
@@ -93,3 +93,13 @@ If you've configured [Development Environment Variables](https://vercel.com/docs
 ```bash
 vercel env pull .env.local
 ```
+
+## Test Environment Variables
+
+Apart from `development` and `production` environments, there is a 3rd option available: `test`. In the same way you can set defaults for development or production environments, you can do the same with `.env.test` file for testing environment (though this one is not so common as the previous two).
+
+This one is useful when running tests with tools like `jest` or `cypress` where you need to set specific environment vars only for testing purposes. Test default values will be loaded if `NODE_ENV` is set to `test`, though you usually don't need to do this manually as testing tools will address it for you.
+
+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`.
diff --git a/docs/basic-features/typescript.md b/docs/basic-features/typescript.md
@@ -43,7 +43,7 @@ You're now ready to start converting files from `.js` to `.tsx` and leveraging t
 
 > Next.js `strict` mode is turned off by default. When you feel comfortable with TypeScript, it's recommended to turn it on in your `tsconfig.json`.
 
-By default, Next.js reports TypeScript errors during development for pages you are actively working on. TypeScript errors for inactive pages **do not** block the development process.
+By default, Next.js will do type checking as part of `next build`. We recommend using code editor type checking during development.
 
 If you want to silence the error reports, refer to the documentation for [Ignoring TypeScript errors](/docs/api-reference/next.config.js/ignoring-typescript-errors.md).
 

diff --git a/docs/routing/dynamic-routes.md b/docs/routing/dynamic-routes.md
@@ -54,7 +54,7 @@ Multiple dynamic route segments work the same way. The page `pages/post/[pid]/[c
 { "pid": "abc", "comment": "a-comment" }
 ```
 
-Client-side navigations to a dynamic route can be handled with [`next/link`](/docs/api-reference/next/link.md#dynamic-routes).
+**Note:** Client-side navigations to a dynamic route (including [catch all routes](#catch-all-routes)) can be handled with [`next/link`](/docs/api-reference/next/link.md#dynamic-routes). Read our docs for [Linking between pages](/docs/routing/introduction#linking-between-pages) to learn more.
 
 ### Catch all routes
 

diff --git a/errors/page-without-valid-component.md b/errors/page-without-valid-component.md
@@ -13,4 +13,4 @@ For each, you'll want to check if the file is meant to be a page.
 
 If the file is not meant to be a page, and instead, is a shared component or file, move the file to a different folder like `components` or `lib`.
 
-If the file is meant to be a page, double check you have an `export default` with the React Component instead of an `export`. If you're already using `export default`, make sure the returned valid is a valid React Component.
+If the file is meant to be a page, double check you have an `export default` with the React Component instead of an `export`. If you're already using `export default`, make sure the returned value is a valid React Component.
diff --git a/errors/prerender-error.md b/errors/prerender-error.md
@@ -7,5 +7,5 @@ While prerendering a page an error occurred. This can occur for many reasons fro
 #### Possible Ways to Fix It
 
 - Make sure to move any non-pages out of the `pages` folder
-- Check for any code that assumes a prop is available even when it might not be
+- Check for any code that assumes a prop is available even when it might not be. e.g., have default data for all dynamic pages' props.
 - Check for any out of date modules that you might be relying on
diff --git a/errors/url-deprecated.md b/errors/url-deprecated.md
@@ -12,7 +12,7 @@ The reason this is going away is that we want to make things very predictable an
 
 https://github.com/zeit/next-codemod#url-to-withrouter
 
-Since Next 5 we provide a way to explicitly inject the Next.js router object into pages and all their decending components.
+Since Next 5 we provide a way to explicitly inject the Next.js router object into pages and all their descending components.
 The `router` property that is injected will hold the same values as `url`, like `pathname`, `asPath`, and `query`.
 
 Here's an example of using `withRouter`:

diff --git a/examples/active-class-name/.gitignore b/examples/active-class-name/.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
diff --git a/examples/amp-first/.gitignore b/examples/amp-first/.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