@@ -21,7 +21,7 @@ To enable AMP support for a page, and to learn more about the different AMP conf
## Caveats
-- Only CSS-in-JS is supported. [CSS Modules](/docs/basic-features/built-in-css-support.md) aren't supported by AMP pages at the moment. You can [contribute CSS Modules support to Next.js](https://github.com/zeit/next.js/issues/10549).
+- Only CSS-in-JS is supported. [CSS Modules](/docs/basic-features/built-in-css-support.md) aren't supported by AMP pages at the moment. You can [contribute CSS Modules support to Next.js](https://github.com/vercel/next.js/issues/10549).
## Related
diff --git a/docs/advanced-features/amp-support/typescript.md b/docs/advanced-features/amp-support/typescript.md
index 273c943d94920..2f284c26d8035 100644
--- a/docs/advanced-features/amp-support/typescript.md
+++ b/docs/advanced-features/amp-support/typescript.md
@@ -6,4 +6,4 @@ description: Using AMP with TypeScript? Extend your typings to allow AMP compone
AMP currently doesn't have built-in types for TypeScript, but it's in their roadmap ([#13791](https://github.com/ampproject/amphtml/issues/13791)).
-As a workaround you can manually create a file called `amp.d.ts` inside your project and add the custom types described [here](https://stackoverflow.com/a/50601125).
+As a workaround you can manually create a file called `amp.d.ts` inside your project and add these [custom types](https://stackoverflow.com/a/50601125).
diff --git a/docs/advanced-features/automatic-static-optimization.md b/docs/advanced-features/automatic-static-optimization.md
index 59315c2bc7eb6..17a3ea787c3b9 100644
--- a/docs/advanced-features/automatic-static-optimization.md
+++ b/docs/advanced-features/automatic-static-optimization.md
@@ -14,29 +14,27 @@ One of the main benefits of this feature is that optimized pages require no serv
## How it works
-If `getServerSideProps` or `getInitialProps` is present in a page, Next.js will use its default behavior and render the page on-demand, per-request (meaning [Server-Side Rendering](/docs/basic-features/pages.md#server-side-rendering)).
+If `getServerSideProps` or `getInitialProps` is present in a page, Next.js will switch to render the page on-demand, per-request (meaning [Server-Side Rendering](/docs/basic-features/pages.md#server-side-rendering)).
If the above is not the case, Next.js will **statically optimize** your page automatically by prerendering the page to static HTML.
-During prerendering, the router's `query` object will be empty since we do not have `query` information to provide during this phase. Any `query` values will be populated client-side after hydration.
+During prerendering, the router's `query` object will be empty since we do not have `query` information to provide during this phase. After hydration, Next.js will trigger an update to your application to provide the route parameters in the `query` object.
> **Note:** Parameters added with [dynamic routes](/docs/routing/dynamic-routes.md) to a page that's using [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) will always be available inside the `query` object.
`next build` will emit `.html` files for statically optimized pages. For example, the result for the page `pages/about.js` would be:
```bash
-.next/server/static/${BUILD_ID}/about.html
+.next/server/pages/about.html
```
And if you add `getServerSideProps` to the page, it will then be JavaScript, like so:
```bash
-.next/server/static/${BUILD_ID}/about.js
+.next/server/pages/about.js
```
-In development you'll know if `pages/about.js` is optimized or not thanks to the included [static optimization indicator](/docs/api-reference/next.config.js/static-optimization-indicator.md).
-
## Caveats
-- If you have a [custom `App`](/docs/advanced-features/custom-app.md) with `getInitialProps` then this optimization will be disabled for all pages.
+- If you have a [custom `App`](/docs/advanced-features/custom-app.md) with `getInitialProps` then this optimization will be turned off in pages without [Static Generation](/docs/basic-features/data-fetching.md#getstaticprops-static-generation).
- If you have a [custom `Document`](/docs/advanced-features/custom-document.md) with `getInitialProps` be sure you check if `ctx.req` is defined before assuming the page is server-side rendered. `ctx.req` will be `undefined` for pages that are prerendered.
diff --git a/docs/advanced-features/codemods.md b/docs/advanced-features/codemods.md
new file mode 100644
index 0000000000000..f897c89f206ea
--- /dev/null
+++ b/docs/advanced-features/codemods.md
@@ -0,0 +1,186 @@
+---
+description: Use codemods to update your codebase when upgrading Next.js to the latest version
+---
+
+# Next.js Codemods
+
+Next.js provides Codemod transformations to help upgrade your Next.js codebase when a feature is deprecated.
+
+Codemods are transformations that run on your codebase programmatically. This allows for a large amount of changes to be applied without having to manually go through every file.
+
+## Usage
+
+`npx @next/codemod `
+
+- `transform` - name of transform, see available transforms below.
+- `path` - files or directory to transform
+- `--dry` Do a dry-run, no code will be edited
+- `--print` Prints the changed output for comparison
+
+## Next.js 11
+
+### `cra-to-next` (experimental)
+
+Migrates a Create React App project to Next.js; creating a pages directory and necessary config to match behavior. Client-side only rendering is leveraged initially to prevent breaking compatibility due to `window` usage during SSR and can be enabled seamlessly to allow gradual adoption of Next.js specific features.
+
+Please share any feedback related to this transform [in this discussion](https://github.com/vercel/next.js/discussions/25858).
+
+## Next.js 10
+
+### `add-missing-react-import`
+
+Transforms files that do not import `React` to include the import in order for the new [React JSX transform](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) to work.
+
+For example:
+
+```jsx
+// my-component.js
+export default class Home extends React.Component {
+ render() {
+ return
Hello World
+ }
+}
+```
+
+Transforms into:
+
+```jsx
+// my-component.js
+import React from 'react'
+export default class Home extends React.Component {
+ render() {
+ return
Hello World
+ }
+}
+```
+
+## Next.js 9
+
+### `name-default-component`
+
+Transforms anonymous components into named components to make sure they work with [Fast Refresh](https://nextjs.org/blog/next-9-4#fast-refresh).
+
+For example:
+
+```jsx
+// my-component.js
+export default function () {
+ return
+}
+```
+
+The component will have a camel cased name based on the name of the file, and it also works with arrow functions.
+
+#### Usage
+
+Go to your project
+
+```
+cd path-to-your-project/
+```
+
+Run the codemod:
+
+```
+npx @next/codemod name-default-component
+```
+
+### `withamp-to-config`
+
+Transforms the `withAmp` HOC into Next.js 9 page configuration.
+
+For example:
+
+```js
+// Before
+import { withAmp } from 'next/amp'
+
+function Home() {
+ return
My AMP Page
+}
+
+export default withAmp(Home)
+```
+
+```js
+// After
+export default function Home() {
+ return
My AMP Page
+}
+
+export const config = {
+ amp: true,
+}
+```
+
+#### Usage
+
+Go to your project
+
+```
+cd path-to-your-project/
+```
+
+Run the codemod:
+
+```
+npx @next/codemod withamp-to-config
+```
+
+## Next.js 6
+
+### `url-to-withrouter`
+
+Transforms the deprecated automatically injected `url` property on top level pages to using `withRouter` and the `router` property it injects. Read more here: [https://nextjs.org/docs/messages/url-deprecated](https://nextjs.org/docs/messages/url-deprecated)
+
+For example:
+
+```js
+// From
+import React from 'react'
+export default class extends React.Component {
+ render() {
+ const { pathname } = this.props.url
+ return
Current pathname: {pathname}
+ }
+}
+```
+
+```js
+// To
+import React from 'react'
+import { withRouter } from 'next/router'
+export default withRouter(
+ class extends React.Component {
+ render() {
+ const { pathname } = this.props.router
+ return
Current pathname: {pathname}
+ }
+ }
+)
+```
+
+This is one case. All the cases that are transformed (and tested) can be found in the [`__testfixtures__` directory](https://github.com/vercel/next.js/tree/canary/packages/next-codemod/transforms/__testfixtures__/url-to-withrouter).
+
+#### Usage
+
+Go to your project
+
+```
+cd path-to-your-project/
+```
+
+Run the codemod:
+
+```
+npx @next/codemod url-to-withrouter
+```
diff --git a/docs/advanced-features/custom-app.md b/docs/advanced-features/custom-app.md
index 1eba8e6fec1c7..71dd20af32577 100644
--- 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:
@@ -38,13 +38,18 @@ export default MyApp
The `Component` prop is the active `page`, so whenever you navigate between routes, `Component` will change to the new `page`. Therefore, any props you send to `Component` will be received by the `page`.
-`pageProps` is an object with the initial props that were preloaded for your page, it's an empty object if the page is not using [`getInitialProps`](/docs/api-reference/data-fetching/getInitialProps.md).
+`pageProps` is an object with the initial props that were preloaded for your page by one of our [data fetching methods](/docs/basic-features/data-fetching.md), otherwise it's an empty object.
-> Adding a custom `getInitialProps` in your `App` will disable [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).
+### Caveats
+
+- If your app is running and you added a custom `App`, you'll need to restart the development server. Only required if `pages/_app.js` didn't exist before.
+- Adding a custom `getInitialProps` in your `App` will disable [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) in pages without [Static Generation](/docs/basic-features/data-fetching.md#getstaticprops-static-generation).
+- When you add `getInitialProps` in your custom app, you must `import App from "next/app"`, call `App.getInitialProps(appContext)` inside `getInitialProps` and merge the returned object into the return value.
+- `App` currently does not support Next.js [Data Fetching methods](/docs/basic-features/data-fetching.md) like [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) or [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering).
### 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
index f1f8aa3348abc..2c75cca86b376 100644
--- 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 `` and `` 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.
+
``, ``, `` and `` 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`:
```
+The `` component used here is not the same one from [`next/head`](/docs/api-reference/next/head.md). The `` component used here should only be used for any `` code that is common for all pages. For all other cases, such as `` 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:
-- `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)
+- `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
-- `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
+- `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 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).
+- `Document` currently does not support Next.js [Data Fetching methods](/docs/basic-features/data-fetching.md) like [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) or [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering).
## Customizing `renderPage`
@@ -71,9 +72,9 @@ class MyDocument extends Document {
ctx.renderPage = () =>
originalRenderPage({
// useful for wrapping the whole react tree
- enhanceApp: App => App,
+ enhanceApp: (App) => App,
// useful for wrapping in a per-page basis
- enhanceComponent: Component => Component,
+ enhanceComponent: (Component) => Component,
})
// Run the parent `getInitialProps`, it now includes the custom `renderPage`
@@ -85,3 +86,21 @@ class MyDocument extends Document {
export default MyDocument
```
+
+## TypeScript
+
+You can use the built-in `DocumentContext` type and change the file name to `./pages/_document.tsx` like so:
+
+```tsx
+import Document, { DocumentContext } from 'next/document'
+
+class MyDocument extends Document {
+ static async getInitialProps(ctx: DocumentContext) {
+ const initialProps = await Document.getInitialProps(ctx)
+
+ return initialProps
+ }
+}
+
+export default MyDocument
+```
diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md
index 64199d2668159..6dfa999892be1 100644
--- 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.
@@ -19,11 +21,26 @@ export default function Custom404() {
}
```
+> **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.
+
## 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 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>
+}
+```
-### Customizing The Error Page
+> **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:
@@ -54,10 +71,9 @@ If you want to render the built-in error page you can by importing the `Error` c
```jsx
import Error from 'next/error'
-import fetch from 'node-fetch'
export async function getServerSideProps() {
- const res = await fetch('https://api.github.com/repos/zeit/next.js')
+ const res = await fetch('https://api.github.com/repos/vercel/next.js')
const errorCode = res.ok ? false : res.statusCode
const json = await res.json()
@@ -76,3 +92,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/custom-server.md b/docs/advanced-features/custom-server.md
index b7ee881c8e3fa..f6d95c59e7b2d 100644
--- a/docs/advanced-features/custom-server.md
+++ b/docs/advanced-features/custom-server.md
@@ -7,17 +7,19 @@ description: Start a Next.js app programmatically using a custom server.
<details>
<summary><b>Examples</b></summary>
<ul>
- <li><a href="/zeit/next.js/tree/canary/examples/custom-server">Basic custom server</a></li>
- <li><a href="/zeit/next.js/tree/canary/examples/custom-server-express">Express integration</a></li>
- <li><a href="/zeit/next.js/tree/canary/examples/custom-server-hapi">Hapi integration</a></li>
- <li><a href="/zeit/next.js/tree/canary/examples/custom-server-koa">Koa integration</a></li>
- <li><a href="/zeit/next.js/tree/canary/examples/ssr-caching">SSR Caching</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/custom-server">Basic custom server</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/custom-server-express">Express integration</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/custom-server-hapi">Hapi integration</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/custom-server-koa">Koa integration</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/ssr-caching">SSR Caching</a></li>
</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.
-> 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).**
+> **Note:** A custom server **can not** be deployed on [Vercel](https://vercel.com/solutions/nextjs).
+
+> 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:
@@ -39,13 +41,13 @@ app.prepare().then(() => {
const { pathname, query } = parsedUrl
if (pathname === '/a') {
- app.render(req, res, '/b', query)
- } else if (pathname === '/b') {
app.render(req, res, '/a', query)
+ } else if (pathname === '/b') {
+ app.render(req, res, '/b', query)
} else {
handle(req, res, parsedUrl)
}
- }).listen(3000, err => {
+ }).listen(3000, (err) => {
if (err) throw err
console.log('> Ready on http://localhost:3000')
})
@@ -94,6 +96,6 @@ 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.
+> Note that `useFileSystemPublicRoutes` 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).
+> 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).
diff --git a/docs/advanced-features/customizing-babel-config.md b/docs/advanced-features/customizing-babel-config.md
index faea0981c88ac..aee52289f1589 100644
--- a/docs/advanced-features/customizing-babel-config.md
+++ b/docs/advanced-features/customizing-babel-config.md
@@ -7,13 +7,13 @@ description: Extend the babel preset added by Next.js with your own configs.
<details>
<summary><b>Examples</b></summary>
<ul>
- <li><a href="/zeit/next.js/tree/canary/examples/with-custom-babel-config">Customizing babel configuration</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/with-custom-babel-config">Customizing babel configuration</a></li>
</ul>
</details>
-Next.js includes the `next/babel` preset to your app, it includes everything needed to compile React applications and server-side code. But if you want to extend the default Babel configs, it's also possible.
+Next.js includes the `next/babel` preset to your app, which includes everything needed to compile React applications and server-side code. But if you want to extend the default Babel configs, it's also possible.
-To start, you only need to define a `.babelrc` file at the top of your app, if such file is found, we're going to consider it the _source of truth_, therefore it needs to define what Next.js needs as well, which is the `next/babel` preset.
+To start, you only need to define a `.babelrc` file (or `babel.config.js`) at the top of your app. If such a file is found, it will be considered as the _source of truth_, and therefore it needs to define what Next.js needs as well, which is the `next/babel` preset.
Here's an example `.babelrc` file:
@@ -24,17 +24,18 @@ Here's an example `.babelrc` file:
}
```
-The `next/babel` presets includes:
+You can [take a look at this file](https://github.com/vercel/next.js/blob/canary/packages/next/build/babel/preset.ts) to learn about the presets included by `next/babel`.
-- preset-env
-- preset-react
-- preset-typescript
-- plugin-proposal-class-properties
-- plugin-proposal-object-rest-spread
-- plugin-transform-runtime
-- styled-jsx
+To add presets/plugins **without configuring them**, you can do it this way:
-To configure these presets/plugins, **do not** add them to `presets` or `plugins` in your custom `.babelrc`. Instead, configure them on the `next/babel` preset, like so:
+```json
+{
+ "presets": ["next/babel"],
+ "plugins": ["@babel/plugin-proposal-do-expressions"]
+}
+```
+
+To add presets/plugins **with custom configuration**, do it on the `next/babel` preset like so:
```json
{
@@ -57,4 +58,4 @@ To learn more about the available options for each config, visit their documenta
> Next.js uses the **current** Node.js version for server-side compilations.
-> The `modules` option on `"preset-env"` should be kept to `false`, otherwise webpack code splitting is disabled.
+> The `modules` option on `"preset-env"` should be kept to `false`, otherwise webpack code splitting is turned off.
diff --git a/docs/advanced-features/customizing-postcss-config.md b/docs/advanced-features/customizing-postcss-config.md
index 0b1cb7bbb2780..b89b4817f11c2 100644
--- a/docs/advanced-features/customizing-postcss-config.md
+++ b/docs/advanced-features/customizing-postcss-config.md
@@ -7,13 +7,13 @@ description: Extend the PostCSS config and plugins added by Next.js with your ow
<details open>
<summary><b>Examples</b></summary>
<ul>
- <li><a href="/zeit/next.js/tree/canary/examples/with-tailwindcss">Tailwind CSS Example</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/with-tailwindcss">Tailwind CSS Example</a></li>
</ul>
</details>
## 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:
@@ -24,10 +24,46 @@ Out of the box, with no configuration, Next.js compiles CSS with the following t
- [Break Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/break-after)
- [`font-variant` Property](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant)
- [Gap Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/gap)
- - [Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/grid)
- [Media Query Ranges](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#Syntax_improvements_in_Level_4)
-By default, [Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/var) (CSS variables) are **not compiled** for IE11 support.
+By default, [CSS Grid](https://www.w3.org/TR/css-grid-1/) and [Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/var) (CSS variables) are **not compiled** for IE11 support.
+
+To compile [CSS Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/grid) for IE11, you can place the following comment at the top of your CSS file:
+
+```css
+/* autoprefixer grid: autoplace */
+```
+
+You can also enable IE11 support for [CSS Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/grid)
+in your entire project by configuring autoprefixer with the configuration shown below (collapsed).
+See ["Customizing Plugins"](#customizing-plugins) below for more information.
+
+<details>
+<summary><strong>Click to view the configuration to enable CSS Grid Layout</strong></summary>
+
+```json
+{
+ "plugins": [
+ "postcss-flexbugs-fixes",
+ [
+ "postcss-preset-env",
+ {
+ "autoprefixer": {
+ "flexbox": "no-2009",
+ "grid": "autoplace"
+ },
+ "stage": 3,
+ "features": {
+ "custom-properties": false
+ }
+ }
+ ]
+ ]
+}
+```
+
+</details>
+<br/>
CSS variables are not compiled because it is [not possible to safely do so](https://github.com/MadLittleMods/postcss-css-variables#caveats).
If you must use variables, consider using something like [Sass variables](https://sass-lang.com/documentation/variables) which are compiled away by [Sass](https://sass-lang.com/).
@@ -50,12 +86,13 @@ 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
> **Warning**: When you define a custom PostCSS configuration file, Next.js **completely disables** the [default behavior](#default-behavior).
> Be sure to manually configure all the features you need compiled, including [Autoprefixer](https://github.com/postcss/autoprefixer).
+> You also need to install any plugins included in your custom configuration manually, i.e. `npm install postcss-flexbugs-fixes postcss-preset-env`.
To customize the PostCSS configuration, create a `postcss.config.json` file in the root of your project.
diff --git a/docs/advanced-features/debugging.md b/docs/advanced-features/debugging.md
new file mode 100644
index 0000000000000..d400d334367db
--- /dev/null
+++ b/docs/advanced-features/debugging.md
@@ -0,0 +1,77 @@
+---
+description: Debug your Next.js app.
+---
+
+# Debugging
+
+This documentation explains how you can debug your Next.js frontend and backend code with full source maps support using either the [Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools) or the [VSCode debugger](https://code.visualstudio.com/docs/editor/debugging).
+
+It requires you to first launch your Next.js application in debug mode in one terminal and then connect an inspector (Chrome DevTools or VS Code) to it.
+
+There might be more ways to debug a Next.js application since all it requires is to expose the Node.js debugger and start an inspector client. You can find more details in the [Node.js documentation](https://nodejs.org/en/docs/guides/debugging-getting-started/).
+
+## Step 1: Start Next.js in debug mode
+
+Next.js being a Node.js application, all we have to do is to pass down the [`--inspect`](https://nodejs.org/api/cli.html#cli_node_options_options) flag to the underlying Node.js process for it to start in debug mode.
+
+First, start Next.js with the inspect flag:
+
+```bash
+NODE_OPTIONS='--inspect' next dev
+```
+
+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"
+```
+
+The result of launching Next.js with the inspect flag looks like this:
+
+```bash
+Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
+For help, see: https://nodejs.org/en/docs/inspector
+ready - started server on http://localhost:3000
+```
+
+> Be aware that using `NODE_OPTIONS='--inspect' npm run dev` or `NODE_OPTIONS='--inspect' yarn dev` won't work. This would try to start multiple debuggers on the same port: one for the npm/yarn process and one for Next.js. You would then get an error like `Starting inspector on 127.0.0.1:9229 failed: address already in use` in your console.
+
+## Step 2: Connect to the debugger
+
+### 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 environment from now on.
+
+### Using the Debugger in Visual Studio Code
+
+We will be using the [attach mode](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_setting-up-an-attach-configuration) of VS Code to attach the VS Code inspector to our running debugger started in step 1.
+
+Create a file named `.vscode/launch.json` at the root of your project with this content:
+
+```json
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "type": "node",
+ "request": "attach",
+ "name": "Attach to application",
+ "skipFiles": ["<node_internals>/**"],
+ "port": 9229
+ }
+ ]
+}
+```
+
+Now hit <kdb>F5</kbd> or select **Debug: Start Debugging** from the Command Palette and you can start your debugging session.
+
+## Step 3: Put breakpoints and see what happens
+
+Now you can use the [`debugger`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger) statement to pause your backend or frontend code anytime you want to observe and debug your code more precisely.
+
+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 appear.
+
+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/advanced-features/dynamic-import.md b/docs/advanced-features/dynamic-import.md
index 547137cbb4187..9bd60726971b5 100644
--- a/docs/advanced-features/dynamic-import.md
+++ b/docs/advanced-features/dynamic-import.md
@@ -4,17 +4,49 @@ description: Dynamically import JavaScript modules and React Components and spli
# Dynamic Import
-<details>
+<details open>
<summary><b>Examples</b></summary>
<ul>
- <li><a href="/zeit/next.js/tree/canary/examples/with-dynamic-import">Dynamic Import</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/with-dynamic-import">Dynamic Import</a></li>
</ul>
</details>
-Next.js supports ES2020 [dynamic `import()`](https://github.com/tc39/proposal-dynamic-import) for JavaScript. With it you can import JavaScript modules (inc. React Components) dynamically and work with them. They also work with SSR.
+Next.js supports ES2020 [dynamic `import()`](https://github.com/tc39/proposal-dynamic-import) for JavaScript. With it you can import JavaScript modules dynamically and work with them. They also work with SSR.
+
+In the following example, we implement fuzzy search using `fuse.js` and only load the module dynamically in the browser after the user types in the search input:
+
+```jsx
+import { useState } from 'react'
+
+const names = ['Tim', 'Joe', 'Bel', 'Max', 'Lee']
+
+export default function Page() {
+ const [results, setResults] = useState()
+
+ return (
+ <div>
+ <input
+ type="text"
+ placeholder="Search"
+ onChange={async (e) => {
+ const { value } = e.currentTarget
+ // Dynamically load fuse.js
+ const Fuse = (await import('fuse.js')).default
+ const fuse = new Fuse(names)
+
+ setResults(fuse.search(value))
+ }}
+ />
+ <pre>Results: {JSON.stringify(results, null, 2)}</pre>
+ </div>
+ )
+}
+```
You can think of dynamic imports as another way to split your code into manageable chunks.
+React components can also be imported using dynamic imports, but in this case we use it in conjunction with `next/dynamic` to make sure it works like any other React Component. Check out the sections below for more details on how it works.
+
## Basic usage
In the following example, the module `../components/hello` will be dynamically loaded by the page:
@@ -39,6 +71,8 @@ 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.
+> **Note**: In `import('path/to/component')`, the path must be explicitly written. It can't be a template string nor a variable. Furthermore the `import()` has to be inside the `dynamic()` call for Next.js to be able to match webpack bundles / module ids to the specific `dynamic()` call and preload them before rendering. `dynamic()` can't be used inside of React rendering as it needs to be marked in the top level of the module for preloading to work, similar to `React.lazy`.
+
## 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`:
@@ -55,7 +89,7 @@ To dynamically import the `Hello` component, you can return it from the [Promise
import dynamic from 'next/dynamic'
const DynamicComponent = dynamic(() =>
- import('../components/hello').then(mod => mod.Hello)
+ import('../components/hello').then((mod) => mod.Hello)
)
function Home() {
@@ -98,7 +132,7 @@ export default Home
## With no SSR
-You may not always want to include a module on server-side, For example, when the module includes a library that only works in the browser.
+You may not always want to include a module on server-side. For example, when the module includes a library that only works in the browser.
Take a look at the following example:
diff --git a/docs/advanced-features/i18n-routing.md b/docs/advanced-features/i18n-routing.md
new file mode 100644
index 0000000000000..5932f80d77461
--- /dev/null
+++ b/docs/advanced-features/i18n-routing.md
@@ -0,0 +1,288 @@
+---
+description: Next.js has built-in support for internationalized routing and language detection. Learn more here.
+---
+
+# Internationalized Routing
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="/vercel/next.js/tree/canary/examples/i18n-routing">i18n routing</a></li>
+ </ul>
+</details>
+
+Next.js has built-in support for internationalized ([i18n](https://en.wikipedia.org/wiki/Internationalization_and_localization#Naming)) routing since `v10.0.0`. You can provide a list of locales, the default locale, and domain-specific locales and Next.js will automatically handle the routing.
+
+The i18n routing support is currently meant to complement existing i18n library solutions like [`react-intl`](https://formatjs.io/docs/getting-started/installation), [`react-i18next`](https://react.i18next.com/), [`lingui`](https://lingui.js.org/), [`rosetta`](https://github.com/lukeed/rosetta), [`next-intl`](https://github.com/amannn/next-intl) and others by streamlining the routes and locale parsing.
+
+## Getting started
+
+To get started, add the `i18n` config to your `next.config.js` file.
+
+Locales are [UTS Locale Identifiers](https://www.unicode.org/reports/tr35/tr35-59/tr35.html#Identifiers), a standardized format for defining locales.
+
+Generally a Locale Identifier is made up of a language, region, and script separated by a dash: `language-region-script`. The region and script are optional. An example:
+
+- `en-US` - English as spoken in the United States
+- `nl-NL` - Dutch as spoken in the Netherlands
+- `nl` - Dutch, no specific region
+
+```js
+// next.config.js
+module.exports = {
+ i18n: {
+ // These are all the locales you want to support in
+ // your application
+ locales: ['en-US', 'fr', 'nl-NL'],
+ // This is the default locale you want to be used when visiting
+ // a non-locale prefixed path e.g. `/hello`
+ defaultLocale: 'en-US',
+ // This is a list of locale domains and the default locale they
+ // should handle (these are only required when setting up domain routing)
+ // Note: subdomains must be included in the domain value to be matched e.g. "fr.example.com".
+ domains: [
+ {
+ domain: 'example.com',
+ defaultLocale: 'en-US',
+ },
+ {
+ domain: 'example.nl',
+ defaultLocale: 'nl-NL',
+ },
+ {
+ domain: 'example.fr',
+ defaultLocale: 'fr',
+ // an optional http field can also be used to test
+ // locale domains locally with http instead of https
+ http: true,
+ },
+ ],
+ },
+}
+```
+
+## Locale Strategies
+
+There are two locale handling strategies: Sub-path Routing and Domain Routing.
+
+### Sub-path Routing
+
+Sub-path Routing puts the locale in the url path.
+
+```js
+// next.config.js
+module.exports = {
+ i18n: {
+ locales: ['en-US', 'fr', 'nl-NL'],
+ defaultLocale: 'en-US',
+ },
+}
+```
+
+With the above configuration `en-US`, `fr`, and `nl-NL` will be available to be routed to, and `en-US` is the default locale. If you have a `pages/blog.js` the following urls would be available:
+
+- `/blog`
+- `/fr/blog`
+- `/nl-nl/blog`
+
+The default locale does not have a prefix.
+
+### Domain Routing
+
+By using domain routing you can configure locales to be served from different domains:
+
+```js
+// next.config.js
+module.exports = {
+ i18n: {
+ locales: ['en-US', 'fr', 'nl-NL', 'nl-BE'],
+ defaultLocale: 'en-US',
+
+ domains: [
+ {
+ domain: 'example.com',
+ defaultLocale: 'en-US',
+ },
+ {
+ domain: 'example.fr',
+ defaultLocale: 'fr',
+ },
+ {
+ domain: 'example.nl',
+ defaultLocale: 'nl-NL',
+ // specify other locales that should be redirected
+ // to this domain
+ locales: ['nl-BE'],
+ },
+ ],
+ },
+}
+```
+
+For example if you have `pages/blog.js` the following urls will be available:
+
+- `example.com/blog`
+- `example.fr/blog`
+- `example.nl/blog`
+- `example.nl/nl-BE/blog`
+
+## Automatic Locale Detection
+
+When a user visits the application root (generally `/`), Next.js will try to automatically detect which locale the user prefers based on the [`Accept-Language`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) header and the current domain.
+
+If a locale other than the default locale is detected, the user will be redirected to either:
+
+- **When using Sub-path Routing:** The locale prefixed path
+- **When using Domain Routing:** The domain with that locale specified as the default
+
+When using Domain Routing, if a user with the `Accept-Language` header `fr;q=0.9` visits `example.com`, they will be redirected to `example.fr` since that domain handles the `fr` locale by default.
+
+When using Sub-path Routing, the user would be redirected to `/fr`.
+
+### Disabling Automatic Locale Detection
+
+The automatic locale detection can be disabled with:
+
+```js
+// next.config.js
+module.exports = {
+ i18n: {
+ localeDetection: false,
+ },
+}
+```
+
+When `localeDetection` is set to `false` Next.js will no longer automatically redirect based on the user's preferred locale and will only provide locale information detected from either the locale based domain or locale path as described above.
+
+## Accessing the locale information
+
+You can access the locale information via the Next.js router. For example, using the [`useRouter()`](/docs/api-reference/next/router.md#userouter) hook the following properties are available:
+
+- `locale` contains the currently active locale.
+- `locales` contains all configured locales.
+- `defaultLocale` contains the configured default locale.
+
+When [pre-rendering](/docs/basic-features/pages.md#static-generation-recommended) pages with `getStaticProps` or `getServerSideProps`, the locale information is provided in [the context](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) provided to the function.
+
+When leveraging `getStaticPaths`, the configured locales are provided in the context parameter of the function under `locales` and the configured defaultLocale under `defaultLocale`.
+
+## Transition between locales
+
+You can use `next/link` or `next/router` to transition between locales.
+
+For `next/link`, a `locale` prop can be provided to transition to a different locale from the currently active one. If no `locale` prop is provided, the currently active `locale` is used during client-transitions. For example:
+
+```jsx
+import Link from 'next/link'
+
+export default function IndexPage(props) {
+ return (
+ <Link href="/another" locale="fr">
+ <a>To /fr/another</a>
+ </Link>
+ )
+}
+```
+
+When using the `next/router` methods directly, you can specify the `locale` that should be used via the transition options. For example:
+
+```jsx
+import { useRouter } from 'next/router'
+
+export default function IndexPage(props) {
+ const router = useRouter()
+
+ return (
+ <div
+ onClick={() => {
+ router.push('/another', '/another', { locale: 'fr' })
+ }}
+ >
+ to /fr/another
+ </div>
+ )
+}
+```
+
+If you have a `href` that already includes the locale you can opt-out of automatically handling the locale prefixing:
+
+```jsx
+import Link from 'next/link'
+
+export default function IndexPage(props) {
+ return (
+ <Link href="/fr/another" locale={false}>
+ <a>To /fr/another</a>
+ </Link>
+ )
+}
+```
+
+## Leveraging the NEXT_LOCALE cookie
+
+Next.js supports overriding the accept-language header with a `NEXT_LOCALE=the-locale` cookie. This cookie can be set using a language switcher and then when a user comes back to the site it will leverage the locale specified in the cookie when redirecting from `/` to the correct locale location.
+
+For example, if a user prefers the locale `fr` in their accept-language header but a `NEXT_LOCALE=en` cookie is set the `en` locale when visiting `/` the user will be redirected to the `en` locale location until the cookie is removed or expired.
+
+## Search Engine Optimization
+
+Since Next.js knows what language the user is visiting it will automatically add the `lang` attribute to the `<html>` tag.
+
+Next.js doesn't know about variants of a page so it's up to you to add the `hreflang` meta tags using [`next/head`](/docs/api-reference/next/head.md). You can learn more about `hreflang` in the [Google Webmasters documentation](https://support.google.com/webmasters/answer/189077).
+
+## How does this work with Static Generation?
+
+> Note that Internationalized Routing does not integrate with [`next export`](/docs/advanced-features/static-html-export.md) as `next export` does not leverage the Next.js routing layer. Hybrid Next.js applications that do not use `next export` are fully supported.
+
+### Automatically Statically Optimized Pages
+
+For pages that are [automatically statically optimized](/docs/advanced-features/automatic-static-optimization.md), a version of the page will be generated for each locale.
+
+### Non-dynamic getStaticProps Pages
+
+For non-dynamic `getStaticProps` pages, a version is generated for each locale like above. `getStaticProps` is called with each `locale` that is being rendered. If you would like to opt-out of a certain locale from being pre-rendered, you can return `notFound: true` from `getStaticProps` and this variant of the page will not be generated.
+
+```js
+export async function getStaticProps({ locale }) {
+ // Call an external API endpoint to get posts.
+ // You can use any data fetching library
+ const res = await fetch(`https://.../posts?locale=${locale}`)
+ const posts = await res.json()
+
+ if (posts.length === 0) {
+ return {
+ notFound: true,
+ }
+ }
+
+ // By returning { props: posts }, the Blog component
+ // will receive `posts` as a prop at build time
+ return {
+ props: {
+ posts,
+ },
+ }
+}
+```
+
+### Dynamic getStaticProps Pages
+
+For dynamic `getStaticProps` pages, any locale variants of the page that is desired to be prerendered needs to be returned from [`getStaticPaths`](/docs/basic-features/data-fetching.md#getstaticpaths-static-generation). Along with the `params` object that can be returned for the `paths`, you can also return a `locale` field specifying which locale you want to render. For example:
+
+```js
+// pages/blog/[slug].js
+export const getStaticPaths = ({ locales }) => {
+ return {
+ paths: [
+ { params: { slug: 'post-1' }, locale: 'en-US' },
+ { params: { slug: 'post-1' }, locale: 'fr' },
+ ],
+ fallback: true,
+ }
+}
+```
+
+## Limits for the i18n config
+
+- `locales`: 100 total locales
+- `domains`: 100 total locale domain items
diff --git a/docs/advanced-features/measuring-performance.md b/docs/advanced-features/measuring-performance.md
new file mode 100644
index 0000000000000..789d94bb8759c
--- /dev/null
+++ b/docs/advanced-features/measuring-performance.md
@@ -0,0 +1,198 @@
+---
+description: Measure and track page performance using Next.js Analytics
+---
+
+# Measuring performance
+
+[Next.js Analytics](https://nextjs.org/analytics) allows you to analyze and measure the performance of
+pages using different metrics.
+
+You can start collecting your [Real Experience Score](https://vercel.com/docs/analytics#metrics) with zero-configuration on [Vercel deployments](https://vercel.com/docs/analytics). There's also support for Analytics if you're [self-hosting](https://vercel.com/docs/analytics#self-hosted).
+
+The rest of this documentation describes the built-in relayer Next.js Analytics uses.
+
+## Build Your Own
+
+First, you will need to create a [custom App](/docs/advanced-features/custom-app.md) component and define a `reportWebVitals` function:
+
+```js
+// pages/_app.js
+export function reportWebVitals(metric) {
+ console.log(metric)
+}
+
+function MyApp({ Component, pageProps }) {
+ return <Component {...pageProps} />
+}
+
+export default MyApp
+```
+
+This function is fired when the final values for any of the metrics have finished calculating on
+the page. You can use to log any of the results to the console or send to a particular endpoint.
+
+The `metric` object returned to the function consists of a number of properties:
+
+- `id`: Unique identifier for the metric in the context of the current page load
+- `name`: Metric name
+- `startTime`: First recorded timestamp of the performance entry in [milliseconds](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp) (if applicable)
+- `value`: Value, or duration in [milliseconds](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp), of the performance entry
+- `label`: Type of metric (`web-vital` or `custom`)
+
+There are two types of metrics that are tracked:
+
+- Web Vitals
+- Custom metrics
+
+## Web Vitals
+
+[Web Vitals](https://web.dev/vitals/) are a set of useful metrics that aim to capture the user
+experience of a web page. The following web vitals are all included:
+
+- [Time to First Byte](https://developer.mozilla.org/en-US/docs/Glossary/Time_to_first_byte) (TTFB)
+- [First Contentful Paint](https://developer.mozilla.org/en-US/docs/Glossary/First_contentful_paint) (FCP)
+- [Largest Contentful Paint](https://web.dev/lcp/) (LCP)
+- [First Input Delay](https://web.dev/fid/) (FID)
+- [Cumulative Layout Shift](https://web.dev/cls/) (CLS)
+
+You can handle all the results of these metrics using the `web-vital` label:
+
+```js
+export function reportWebVitals(metric) {
+ if (metric.label === 'web-vital') {
+ console.log(metric) // The metric object ({ id, name, startTime, value, label }) is logged to the console
+ }
+}
+```
+
+There's also the option of handling each of the metrics separately:
+
+```js
+export function reportWebVitals(metric) {
+ switch (metric.name) {
+ case 'FCP':
+ // handle FCP results
+ break
+ case 'LCP':
+ // handle LCP results
+ break
+ case 'CLS':
+ // handle CLS results
+ break
+ case 'FID':
+ // handle FID results
+ break
+ case 'TTFB':
+ // handle TTFB results
+ break
+ default:
+ break
+ }
+}
+```
+
+A third-party library, [web-vitals](https://github.com/GoogleChrome/web-vitals), is used to measure
+these metrics. Browser compatibility depends on the particular metric, so refer to the [Browser
+Support](https://github.com/GoogleChrome/web-vitals#browser-support) section to find out which
+browsers are supported.
+
+## Custom metrics
+
+In addition to the core metrics listed above, there are some additional custom metrics that
+measure the time it takes for the page to hydrate and render:
+
+- `Next.js-hydration`: Length of time it takes for the page to start and finish hydrating (in ms)
+- `Next.js-route-change-to-render`: Length of time it takes for a page to start rendering after a
+ route change (in ms)
+- `Next.js-render`: Length of time it takes for a page to finish render after a route change (in ms)
+
+You can handle all the results of these metrics using the `custom` label:
+
+```js
+export function reportWebVitals(metric) {
+ if (metric.label === 'custom') {
+ console.log(metric) // The metric object ({ id, name, startTime, value, label }) is logged to the console
+ }
+}
+```
+
+There's also the option of handling each of the metrics separately:
+
+```js
+export function reportWebVitals(metric) {
+ switch (metric.name) {
+ case 'Next.js-hydration':
+ // handle hydration results
+ break
+ case 'Next.js-route-change-to-render':
+ // handle route-change to render results
+ break
+ case 'Next.js-render':
+ // handle render results
+ break
+ default:
+ break
+ }
+}
+```
+
+These metrics work in all browsers that support the [User Timing API](https://caniuse.com/#feat=user-timing).
+
+## Sending results to analytics
+
+With the relay function, you can send any of results to an analytics endpoint to measure and track
+real user performance on your site. For example:
+
+```js
+export function reportWebVitals(metric) {
+ const body = JSON.stringify(metric)
+ const url = 'https://example.com/analytics'
+
+ // Use `navigator.sendBeacon()` if available, falling back to `fetch()`.
+ if (navigator.sendBeacon) {
+ navigator.sendBeacon(url, body)
+ } else {
+ fetch(url, { body, method: 'POST', keepalive: true })
+ }
+}
+```
+
+> **Note**: If you use [Google Analytics](https://analytics.google.com/analytics/web/), using the
+> `id` value can allow you to construct metric distributions manually (to calculate percentiles,
+> etc...).
+>
+> ```js
+> export function reportWebVitals({ id, name, label, value }) {
+> // 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('event', name, {
+> event_category:
+> label === 'web-vital' ? 'Web Vitals' : 'Next.js custom metric',
+> value: Math.round(name === 'CLS' ? value * 1000 : value), // values must be integers
+> event_label: id, // id unique to current page load
+> non_interaction: true, // avoids affecting bounce rate.
+> })
+> }
+> ```
+>
+> Read more about [sending results to Google Analytics](https://github.com/GoogleChrome/web-vitals#send-the-results-to-google-analytics).
+
+## TypeScript
+
+If you are using TypeScript, you can use the built-in type `NextWebVitalsMetric`:
+
+```ts
+// pages/_app.tsx
+
+import type { AppProps, NextWebVitalsMetric } from 'next/app'
+
+function MyApp({ Component, pageProps }: AppProps) {
+ return <Component {...pageProps} />
+}
+
+export function reportWebVitals(metric: NextWebVitalsMetric) {
+ console.log(metric)
+}
+
+export default MyApp
+```
diff --git a/docs/advanced-features/module-path-aliases.md b/docs/advanced-features/module-path-aliases.md
new file mode 100644
index 0000000000000..8015f82667cd0
--- /dev/null
+++ b/docs/advanced-features/module-path-aliases.md
@@ -0,0 +1,95 @@
+---
+description: Configure module path aliases that allow you to remap certain import paths.
+---
+
+# Absolute Imports and Module path aliases
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="/vercel/next.js/tree/canary/examples/with-absolute-imports">Absolute Imports</a></li>
+ </ul>
+</details>
+
+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
+
+> 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.
+
+The `baseUrl` configuration option allows you to import directly from the root of the project.
+
+An example of this configuration:
+
+```json
+// tsconfig.json or jsconfig.json
+{
+ "compilerOptions": {
+ "baseUrl": "."
+ }
+}
+```
+
+```jsx
+// components/button.js
+export default function Button() {
+ return <button>Click me</button>
+}
+```
+
+```jsx
+// pages/index.js
+import Button from 'components/button'
+
+export default function HomePage() {
+ return (
+ <>
+ <h1>Hello World</h1>
+ <Button />
+ </>
+ )
+}
+```
+
+While `baseUrl` is useful you might want to add other aliases that don't match 1 on 1. For this TypeScript has the `"paths"` option.
+
+Using `"paths"` allows you to configure module aliases. For example `@/components/*` to `components/*`.
+
+An example of this configuration:
+
+```json
+// tsconfig.json or jsconfig.json
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "paths": {
+ "@/components/*": ["components/*"]
+ }
+ }
+}
+```
+
+```jsx
+// components/button.js
+export default function Button() {
+ return <button>Click me</button>
+}
+```
+
+```jsx
+// pages/index.js
+import Button from '@/components/button'
+
+export default function HomePage() {
+ return (
+ <>
+ <h1>Hello World</h1>
+ <Button />
+ </>
+ )
+}
+```
diff --git a/docs/advanced-features/multi-zones.md b/docs/advanced-features/multi-zones.md
index 2a9883a2541d5..7d288941b0cb9 100644
--- a/docs/advanced-features/multi-zones.md
+++ b/docs/advanced-features/multi-zones.md
@@ -1,9 +1,9 @@
# Multi Zones
-<details>
+<details open>
<summary><b>Examples</b></summary>
<ul>
- <li><a href="/examples/with-zones">With Zones</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/with-zones">With Zones</a></li>
</ul>
</details>
@@ -18,30 +18,13 @@ With multi zones support, you can merge both these apps into a single one allowi
## How to define a zone
-There are no special zones related APIs. You only need to do following:
+There are no zone related APIs. You only need to do the following:
- Make sure to keep only the pages you need in your app, meaning that an app can't have pages from another app, if app `A` has `/blog` then app `B` shouldn't have it too.
-- Make sure to add an [assetPrefix](/docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md) to avoid conflicts with static files.
+- Make sure to configure a [basePath](/docs/api-reference/next.config.js/basepath.md) to avoid conflicts with pages and static files.
## How to merge zones
-You can merge zones using any HTTP proxy.
-
-For [ZEIT Now](https://zeit.co/now), you can use a single `now.json` to deploy both apps. It allows you to easily define routing routes for multiple apps like below:
-
-```json
-{
- "version": 2,
- "builds": [
- { "src": "blog/package.json", "use": "@now/next" },
- { "src": "home/package.json", "use": "@now/next" }
- ],
- "routes": [
- { "src": "/blog/_next(.*)", "dest": "blog/_next$1" },
- { "src": "/blog(.*)", "dest": "blog/blog$1" },
- { "src": "(.*)", "dest": "home$1" }
- ]
-}
-```
-
-You can also configure a proxy server to route using a set of routes like the ones above, e.g deploy the blog app to `https://blog.example.com` and the home app to `https://home.example.com` and then add a proxy server for both apps in `https://example.com`.
+You can merge zones using [Rewrites](/docs/api-reference/next.config.js/rewrites.md) in one of the apps or any HTTP proxy.
+
+For [Vercel](https://vercel.com/), you can use a [monorepo](https://vercel.com/blog/monorepos) to deploy both apps. Check the [Monorepos blog post](https://vercel.com/blog/monorepos) for more details on how it works and our [`with-zones` example](https://github.com/vercel/next.js/tree/canary/examples/with-zones) for a detailed guide using multiple Next.js applications.
diff --git a/docs/advanced-features/preview-mode.md b/docs/advanced-features/preview-mode.md
index d5cc52607c57d..98d1ae6698cb8 100644
--- a/docs/advanced-features/preview-mode.md
+++ b/docs/advanced-features/preview-mode.md
@@ -6,11 +6,31 @@ description: Next.js has the preview mode for statically generated pages. You ca
> This document is for Next.js versions 9.3 and up. If you’re using older versions of Next.js, refer to our [previous documentation](https://nextjs.org/docs/tag/v9.2.2/basic-features/pages).
+<details open>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-wordpress">WordPress Example</a> (<a href="https://next-blog-wordpress.vercel.app">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-datocms">DatoCMS Example</a> (<a href="https://next-blog-datocms.vercel.app/">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-takeshape">TakeShape Example</a> (<a href="https://next-blog-takeshape.vercel.app/">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-sanity">Sanity Example</a> (<a href="https://next-blog-sanity.vercel.app/">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-prismic">Prismic Example</a> (<a href="https://next-blog-prismic.vercel.app/">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-contentful">Contentful Example</a> (<a href="https://next-blog-contentful.vercel.app/">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-strapi">Strapi Example</a> (<a href="https://next-blog-strapi.vercel.app/">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-prepr">Prepr Example</a> (<a href="https://next-blog-prepr.vercel.app/">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-agilitycms">Agility CMS Example</a> (<a href="https://next-blog-agilitycms.vercel.app/">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-cosmic">Cosmic Example</a> (<a href="https://next-blog-cosmic.vercel.app/">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-buttercms">ButterCMS Example</a> (<a href="https://next-blog-buttercms.vercel.app/">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-storyblok">Storyblok Example</a> (<a href="https://next-blog-storyblok.vercel.app/">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-graphcms">GraphCMS Example</a> (<a href="https://next-blog-graphcms.vercel.app/">Demo</a>)</li>
+ <li><a href="/vercel/next.js/tree/canary/examples/cms-kontent">Kontent Example</a> (<a href="https://next-blog-kontent.vercel.app//">Demo</a>)</li>
+ </ul>
+</details>
+
In the [Pages documentation](/docs/basic-features/pages.md) and the [Data Fetching documentation](/docs/basic-features/data-fetching.md), we talked about how to pre-render a page at build time (**Static Generation**) using `getStaticProps` and `getStaticPaths`.
-Static Generation is useful when your pages fetch data from a headless CMS. However, it’s not ideal when you’re writing a draft on your headless CMS and want to **preview** the draft immediately on your page. You’d want to Next.js to render these pages at **request time** instead of build time and fetch the draft content instead of the published content. You’d want Next.js to bypass Static Generation only for this specific case.
+Static Generation is useful when your pages fetch data from a headless CMS. However, it’s not ideal when you’re writing a draft on your headless CMS and want to **preview** the draft immediately on your page. You’d want Next.js to render these pages at **request time** instead of build time and fetch the draft content instead of the published content. You’d want Next.js to bypass Static Generation only for this specific case.
-Next.js has the feature called **Preview Mode** which solves this problem. Here’s an instruction on how to use it.
+Next.js has a feature called **Preview Mode** which solves this problem. Here are instructions on how to use it.
## Step 1. Create and access a preview API route
@@ -18,10 +38,10 @@ Next.js has the feature called **Preview Mode** which solves this problem. Here
First, create a **preview API route**. It can have any name - e.g. `pages/api/preview.js` (or `.ts` if using TypeScript).
-In this API route, you need to call `setPreviewData` on the response object. The argument for `setPreviewData` should be an object, and this can be used by `getStaticProps` (more on this later). For now, we’ll just use `{}`.
+In this API route, you need to call `setPreviewData` on the response object. The argument for `setPreviewData` should be an object, and this can be used by `getStaticProps` (more on this later). For now, we’ll use `{}`.
```js
-export default (req, res) => {
+export default function handler(req, res) {
// ...
res.setPreviewData({})
// ...
@@ -36,7 +56,7 @@ You can test this manually by creating an API route like below and accessing it
// A simple example for testing it manually from your browser.
// If this is located at pages/api/preview.js, then
// open /api/preview from your browser.
-export default (req, res) => {
+export default function handler(req, res) {
res.setPreviewData({})
res.end('Preview mode enabled')
}
@@ -93,8 +113,7 @@ export default async (req, res) => {
// Redirect to the path from the fetched post
// We don't redirect to req.query.slug as that might lead to open redirect vulnerabilities
- res.writeHead(307, { Location: post.slug })
- res.end()
+ res.redirect(post.slug)
}
```
@@ -149,15 +168,6 @@ That’s it! If you access the preview API route (with `secret` and `slug`) from
https://<your-site>/api/preview?secret=<token>&slug=<path>
```
-## More Examples
-
-Take a look at the following examples to learn more:
-
-- [DatoCMS Example](https://github.com/zeit/next.js/tree/canary/examples/cms-datocms) ([Demo](https://next-blog-datocms.now.sh/))
-- [TakeShape Example](https://github.com/zeit/next.js/tree/canary/examples/cms-takeshape) ([Demo](https://next-blog-takeshape.now.sh/))
-- [Sanity Example](https://github.com/zeit/next.js/tree/canary/examples/cms-sanity) ([Demo](https://next-blog-sanity.now.sh/))
-- [Prismic Example](https://github.com/zeit/next.js/tree/canary/examples/cms-prismic) ([Demo](https://next-blog-prismic.now.sh/))
-
## More Details
### Clear the preview mode cookies
@@ -167,7 +177,7 @@ By default, no expiration date is set for the preview mode cookies, so the previ
To clear the preview cookies manually, you can create an API route which calls `clearPreviewData` and then access this API route.
```js
-export default (req, res) => {
+export default function handler(req, res) {
// Clears the preview mode cookies.
// This function accepts no arguments.
res.clearPreviewData()
@@ -195,9 +205,24 @@ 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`
-The bypass cookie value and private key for encrypting the `previewData` changes when a `next build` is ran, this ensures that the bypass cookie can’t be guessed.
+Both the bypass cookie value and the private key for encrypting the `previewData` change when `next build` is completed.
+This ensures that the bypass cookie can’t be guessed.
+
+> **Note:** To test Preview Mode locally over HTTP your browser will need to allow third-party cookies and local storage access.
## Learn more
diff --git a/docs/advanced-features/security-headers.md b/docs/advanced-features/security-headers.md
new file mode 100644
index 0000000000000..c51718bdcb08e
--- /dev/null
+++ b/docs/advanced-features/security-headers.md
@@ -0,0 +1,139 @@
+---
+description: Improve the security of your Next.js application by adding HTTP response headers.
+---
+
+# Security Headers
+
+To improve the security of your application, you can use [`headers`](/docs/api-reference/next.config.js/headers.md) in `next.config.js` to apply HTTP response headers to all routes in your application.
+
+```jsx
+// next.config.js
+
+// You can choose which headers to add to the list
+// after learning more below.
+const securityHeaders = []
+
+module.exports = {
+ async headers() {
+ return [
+ {
+ // Apply these headers to all routes in your application.
+ source: '/(.*)',
+ headers: securityHeaders,
+ },
+ ]
+ },
+}
+```
+
+## Options
+
+### [X-DNS-Prefetch-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control)
+
+This header controls DNS prefetching, allowing browsers to proactively perform domain name resolution on external links, images, CSS, JavaScript, and more. This prefetching is performed in the background, so the [DNS](https://developer.mozilla.org/en-US/docs/Glossary/DNS) is more likely to be resolved by the time the referenced items are needed. This reduces latency when the user clicks a link.
+
+```jsx
+{
+ key: 'X-DNS-Prefetch-Control',
+ value: 'on'
+}
+```
+
+### [Strict-Transport-Security](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security)
+
+This header informs browsers it should only be accessed using HTTPS, instead of using HTTP. Using the configuration below, all present and future subdomains will use HTTPS for a `max-age` of 2 years. This blocks access to pages or subdomains that can only be served over HTTP.
+
+If you're deploying to [Vercel](https://vercel.com/docs/edge-network/headers#strict-transport-security), this header is not necessary as it's automatically added to all deployments.
+
+```jsx
+{
+ key: 'Strict-Transport-Security',
+ value: 'max-age=63072000; includeSubDomains; preload'
+}
+```
+
+### [X-XSS-Protection](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection)
+
+This header stops pages from loading when they detect reflected cross-site scripting (XSS) attacks. Although this protection is not necessary when sites implement a strong [`Content-Security-Policy`](#content-security-policy) disabling the use of inline JavaScript (`'unsafe-inline'`), it can still provide protection for older web browsers that don't support CSP.
+
+```jsx
+{
+ key: 'X-XSS-Protection',
+ value: '1; mode=block'
+}
+```
+
+### [X-Frame-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options)
+
+This header indicates whether the site should be allowed to be displayed within an `iframe`. This can prevent against clickjacking attacks. This header has been superseded by CSP's `frame-ancestors` option, which has better support in modern browsers.
+
+```jsx
+{
+ key: 'X-Frame-Options',
+ value: 'SAMEORIGIN'
+}
+```
+
+### [Permissions-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy)
+
+This header allows you to control which features and APIs can be used in the browser. It was previously named `Feature-Policy`. You can view the full list of permission options [here](https://www.w3.org/TR/permissions-policy-1/).
+
+```jsx
+{
+ key: 'Permissions-Policy',
+ value: 'camera=(), microphone=(), geolocation=(), interest-cohort=()'
+}
+```
+
+### [X-Content-Type-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options)
+
+This header prevents the browser from attempting to guess the type of content if the `Content-Type` header is not explicitly set. This can prevent XSS exploits for websites that allow users to upload and share files. For example, a user trying to download an image, but having it treated as a different `Content-Type` like an executable, which could be malicious. This header also applies to downloading browser extensions. The only valid value for this header is `nosniff`.
+
+```jsx
+{
+ key: 'X-Content-Type-Options',
+ value: 'nosniff'
+}
+```
+
+### [Referrer-Policy](https://scotthelme.co.uk/a-new-security-header-referrer-policy/)
+
+This header controls how much information the browser includes when navigating from the current website (origin) to another. You can read about the different options [here](https://scotthelme.co.uk/a-new-security-header-referrer-policy/).
+
+```jsx
+{
+ key: 'Referrer-Policy',
+ value: 'origin-when-cross-origin'
+}
+```
+
+### [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
+
+This header helps prevent cross-site scripting (XSS), clickjacking and other code injection attacks. Content Security Policy (CSP) can specify allowed origins for content including scripts, stylesheets, images, fonts, objects, media (audio, video), iframes, and more.
+
+You can read about the many different CSP options [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP).
+
+```jsx
+{
+ key: 'Content-Security-Policy',
+ value: // Your CSP Policy
+}
+```
+
+### References
+
+- [MDN](https://developer.mozilla.org)
+- [Varun Naik](https://blog.vnaik.com/posts/web-attacks.html)
+- [Scott Helme](https://scotthelme.co.uk)
+- [Mozilla Observatory](https://observatory.mozilla.org/)
+
+## Related
+
+For more information, we recommend the following sections:
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/headers.md">
+ <b>Headers:</b>
+ <small>Add custom HTTP headers to your Next.js app.</small>
+ </a>
+</div>
diff --git a/docs/advanced-features/source-maps.md b/docs/advanced-features/source-maps.md
new file mode 100644
index 0000000000000..aa07ea4cf5982
--- /dev/null
+++ b/docs/advanced-features/source-maps.md
@@ -0,0 +1,23 @@
+---
+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 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:
+
+```js
+// next.config.js
+module.exports = {
+ productionBrowserSourceMaps: true,
+}
+```
+
+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
+
+- Adding source maps can increase `next build` time
+- Increases memory usage during `next build`
diff --git a/docs/advanced-features/static-html-export.md b/docs/advanced-features/static-html-export.md
index 4b2f09da7c1cf..c217b55d952ac 100644
--- a/docs/advanced-features/static-html-export.md
+++ b/docs/advanced-features/static-html-export.md
@@ -7,7 +7,7 @@ description: Export your Next.js app to static HTML, and run it standalone witho
<details>
<summary><b>Examples</b></summary>
<ul>
- <li><a href="/zeit/next.js/tree/canary/examples/with-static-export">Static Export</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/with-static-export">Static Export</a></li>
</ul>
</details>
@@ -15,13 +15,17 @@ description: Export your Next.js app to static HTML, and run it standalone witho
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 called [`exportPathMap`](/docs/api-reference/next.config.js/exportPathMap.md) which offers a way to pre-define paths you will render as html.
+`next export` works by prerendering all pages to HTML. For [dynamic routes](/docs/routing/dynamic-routes.md), your page can export a [`getStaticPaths`](/docs/basic-features/data-fetching.md#getstaticpaths-static-generation) function to let the exporter know which HTML pages to generate for that route.
-> 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).
+> `next export` is intended for scenarios where **none** of your pages have server-side or incremental data requirements (though statically-rendered pages can still [fetch data on the client side](/docs/basic-features/data-fetching.md#fetching-data-on-the-client-side)).
+>
+> 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](/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
-Simply develop your app as you normally do with Next.js. Then run:
+Develop your app as you normally do with Next.js. Then run:
```bash
next build && next export
@@ -35,7 +39,7 @@ For that you may want to update the scripts in your `package.json` like this:
}
```
-And run it at once with:
+And run it with:
```bash
npm run build
@@ -43,16 +47,29 @@ npm run build
Then you'll have a static version of your app in the `out` directory.
-By default `next export` doesn't require any configuration. It will generate a default `exportPathMap` with routes for the pages inside the `pages` directory.
-
-> To learn more about `exportPathMap` please visit the [documentation for the `exportPathMap` API](/docs/api-reference/next.config.js/exportPathMap.md).
+By default `next export` doesn't require any configuration.
+It will output a static HTML file for each page in your `pages` directory (or more for [dynamic routes](/docs/routing/dynamic-routes.md), where it will call [`getStaticPaths`](/docs/basic-features/data-fetching.md#getstaticpaths-static-generation) and generate pages based on the result).
+For more advanced scenarios, you can define a parameter called [`exportPathMap`](/docs/api-reference/next.config.js/exportPathMap.md) in your [`next.config.js`](/docs/api-reference/next.config.js/introduction.md) file to configure exactly which pages will be generated.
## 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
-- 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).
+- With `next export`, we build an HTML version of your app. At export time, we call [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) for each page that exports it, and pass the result to the page's component. It's also possible to use the older [`getInitialProps`](/docs/api-reference/data-fetching/getInitialProps.md) API instead of `getStaticProps`, but it comes with a few caveats:
+
+ - `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` should fetch from an API and cannot use Node.js-specific libraries or the file system like `getStaticProps` can.
+
+ It's recommended to use and migrate towards `getStaticProps` over `getInitialProps` whenever possible.
+
+- 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.
+- [Internationalized Routing](/docs/advanced-features/i18n-routing.md) is not supported as it requires Next.js' server-side routing.
+- The [`next/image`](/docs/api-reference/next/image.md) component's default loader is not supported when using `next export`. However, other [loader](/docs/basic-features/image-optimization.md#loader) options will work.
diff --git a/docs/api-reference/cli.md b/docs/api-reference/cli.md
index 5b4de22e6301d..b79edb5f0bbce 100644
--- a/docs/api-reference/cli.md
+++ b/docs/api-reference/cli.md
@@ -21,7 +21,7 @@ Usage
$ next <command>
Available commands
- build, start, export, dev, telemetry
+ build, start, export, dev, lint, telemetry
Options
--version, -v Version number
@@ -38,3 +38,90 @@ NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next
```
+
+## Build
+
+`next build` creates an optimized production build of your application. The output displays information about each route.
+
+- **Size** – The number of assets downloaded when navigating to the page client-side. The size for each route only includes its dependencies.
+- **First Load JS** – The number of assets downloaded when visiting the page from the server. The amount of JS shared by all is shown as a separate metric.
+
+The first load is indicated by 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](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:
+
+The application will start at `http://localhost:3000` by default. The default port can be changed with `-p`, like so:
+
+```bash
+npx next dev -p 4000
+```
+
+Or using the `PORT` environment variable:
+
+```bash
+PORT=4000 npx next dev
+```
+
+> Note: `PORT` can not be set in `.env` as booting up the HTTP server happens before any other code is initialized.
+
+You can also set the hostname to be different from the default of `0.0.0.0`, this can be useful for making the application available for other devices on the network. The default hostname can be changed with `-H`, like so:
+
+```bash
+npx next dev -H 192.168.1.2
+```
+
+## Production
+
+`next start` starts the application in production mode. The application should be compiled with [`next build`](#build) first.
+
+The application will start at `http://localhost:3000` by default. The default port can be changed with `-p`, like so:
+
+```bash
+npx next start -p 4000
+```
+
+Or using the `PORT` environment variable:
+
+```bash
+PORT=4000 npx next start
+```
+
+> Note: `PORT` can not be set in `.env` as booting up the HTTP server happens before any other code is initialized.
+
+## Lint
+
+`next lint` runs ESLint for all files in the `pages`, `components`, and `lib` directories. It also
+provides a guided setup to install any required dependencies if ESLint is not already configured in
+your application.
+
+If you have other directories that you would like to lint, you can specify them using the `--dir`
+flag:
+
+```bash
+next lint --dir utils
+```
+
+## Telemetry
+
+Next.js collects **completely anonymous** telemetry data about general usage.
+Participation in this anonymous program is optional, and you may opt-out if you'd not like to share any information.
+
+To learn more about Telemetry, [please read this document](https://nextjs.org/telemetry/).
diff --git a/docs/api-reference/create-next-app.md b/docs/api-reference/create-next-app.md
new file mode 100644
index 0000000000000..1192865d09c00
--- /dev/null
+++ b/docs/api-reference/create-next-app.md
@@ -0,0 +1,65 @@
+---
+description: Create Next.js apps in one command with create-next-app.
+---
+
+# Create Next App
+
+The easiest way to get started with Next.js is by using `create-next-app`. This CLI tool enables you to quickly start building a new Next.js application, with everything set up for you. You can create a new app using the default Next.js template, or by using one of the [official Next.js examples](https://github.com/vercel/next.js/tree/canary/examples). To get started, use the following command:
+
+```bash
+npx create-next-app
+# or
+yarn create next-app
+```
+
+You can create a [TypeScript project](https://github.com/vercel/next.js/blob/canary/docs/basic-features/typescript.md) with the `--ts, --typescript` flag:
+
+```bash
+npx create-next-app --ts
+# or
+yarn create next-app --typescript
+```
+
+### Options
+
+`create-next-app` comes with the following options:
+
+- **--ts, --typescript** - Initialize as a TypeScript project.
+- **-e, --example [name]|[github-url]** - An example to bootstrap the app with. You can use an example name from the [Next.js repo](https://github.com/vercel/next.js/tree/master/examples) or a GitHub URL. The URL can use any branch and/or subdirectory.
+- **--example-path [path-to-example]** - In a rare case, your GitHub URL might contain a branch name with a slash (e.g. bug/fix-1) and the path to the example (e.g. foo/bar). In this case, you must specify the path to the example separately: `--example-path foo/bar`
+- **--use-npm** - Explicitly tell the CLI to bootstrap the app using npm. To bootstrap using yarn we recommend running `yarn create next-app`
+
+### Why use Create Next App?
+
+`create-next-app` allows you to create a new Next.js app within seconds. It is officially maintained by the creators of Next.js, and includes a number of benefits:
+
+- **Interactive Experience**: Running `npx create-next-app` (with no arguments) launches an interactive experience that guides you through setting up a project.
+- **Zero Dependencies**: Initializing a project is as quick as one second. Create Next App has zero dependencies.
+- **Offline Support**: Create Next App will automatically detect if you're offline and bootstrap your project using your local package cache.
+- **Support for Examples**: Create Next App can bootstrap your application using an example from the Next.js examples collection (e.g. `npx create-next-app --example api-routes`).
+- **Tested**: The package is part of the Next.js monorepo and tested using the same integration test suite as Next.js itself, ensuring it works as expected with every release.
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+<div class="card">
+ <a href="/docs/basic-features/pages.md">
+ <b>Pages:</b>
+ <small>Learn more about what pages are in Next.js.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/basic-features/built-in-css-support.md">
+ <b>CSS Support:</b>
+ <small>Use the built-in CSS support to add custom styles to your app.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/api-reference/cli.md">
+ <b>CLI:</b>
+ <small>Learn more about the Next.js CLI.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/data-fetching/getInitialProps.md b/docs/api-reference/data-fetching/getInitialProps.md
index b20a2ab9f4f20..f46b34615f563 100644
--- a/docs/api-reference/data-fetching/getInitialProps.md
+++ b/docs/api-reference/data-fetching/getInitialProps.md
@@ -4,35 +4,25 @@ 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="/zeit/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).
> `getInitialProps` will disable [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).
-`getInitialProps` is an [`async`](https://zeit.co/blog/async-and-await) function that can be added to any page as a [`static method`](https://javascript.info/static-properties-methods). Take a look at the following example:
+`getInitialProps` is an [`async`](https://vercel.com/blog/async-and-await) function that can be added to any page as a [`static method`](https://javascript.info/static-properties-methods). Take a look at the following example:
```jsx
-import fetch from 'isomorphic-unfetch'
-
function Page({ stars }) {
return <div>Next stars: {stars}</div>
}
-Page.getInitialProps = async ctx => {
- const res = await fetch('https://api.github.com/repos/zeit/next.js')
+Page.getInitialProps = async (ctx) => {
+ const res = await fetch('https://api.github.com/repos/vercel/next.js')
const json = await res.json()
return { stars: json.stargazers_count }
}
@@ -44,11 +34,10 @@ Or using a class component:
```jsx
import React from 'react'
-import fetch from 'isomorphic-unfetch'
class Page extends React.Component {
static async getInitialProps(ctx) {
- const res = await fetch('https://api.github.com/repos/zeit/next.js')
+ const res = await fetch('https://api.github.com/repos/vercel/next.js')
const json = await res.json()
return { stars: json.stargazers_count }
}
@@ -65,7 +54,7 @@ export default Page
Data returned from `getInitialProps` is serialized when server rendering, similar to what [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) does. Make sure the returned object from `getInitialProps` is a plain `Object` and not using `Date`, `Map` or `Set`.
-For the initial page load, `getInitialProps` will execute on the server only. `getInitialProps` will only be executed on the client when navigating to a different route via the [`next/link`](/docs/api-reference/next/link.md) component or by using [`next/router`](/docs/api-reference/next/router.md).
+For the initial page load, `getInitialProps` will run on the server only. `getInitialProps` will then run on the client when navigating to a different route via the [`next/link`](/docs/api-reference/next/link.md) component or by using [`next/router`](/docs/api-reference/next/router.md). However, if `getInitialProps` is used in a custom `_app.js`, and the page being navigated to implements `getServerSideProps`, then `getInitialProps` will run on the server.
## Context Object
@@ -74,8 +63,8 @@ For the initial page load, `getInitialProps` will execute on the server only. `g
- `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/basepath.md b/docs/api-reference/next.config.js/basepath.md
new file mode 100644
index 0000000000000..0df919b35a057
--- /dev/null
+++ b/docs/api-reference/next.config.js/basepath.md
@@ -0,0 +1,79 @@
+---
+description: Learn more about setting a base path in Next.js
+---
+
+# Base Path
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| -------- | ---------------- |
+| `v9.5.0` | Base Path added. |
+
+</details>
+
+To deploy a Next.js application under a sub-path of a domain you can use the `basePath` config option.
+
+`basePath` allows you to set a path prefix for the application. For example, to use `/docs` instead of `/` (the default), open `next.config.js` and add the `basePath` config:
+
+```js
+module.exports = {
+ basePath: '/docs',
+}
+```
+
+Note: this value must be set at build time and can not be changed without re-building as the value is inlined in the client-side bundles.
+
+## Links
+
+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`.
+
+```js
+export default function HomePage() {
+ return (
+ <>
+ <Link href="/about">
+ <a>About Page</a>
+ </Link>
+ </>
+ )
+}
+```
+
+Output html:
+
+```html
+<a href="/docs/about">About Page</a>
+```
+
+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
+```
diff --git a/docs/api-reference/next.config.js/build-target.md b/docs/api-reference/next.config.js/build-target.md
deleted file mode 100644
index fffd743340e9d..0000000000000
--- a/docs/api-reference/next.config.js/build-target.md
+++ /dev/null
@@ -1,47 +0,0 @@
----
-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.
-
-## `server` target
-
-> 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) will automatically enable this target. You should not opt-into it yourself.
-
-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`:
-
-```js
-module.exports = {
- target: 'serverless',
-}
-```
-
-## Related
-
-<div class="card">
- <a href="/docs/api-reference/next.config.js/introduction.md">
- <b>Introduction to next.config.js:</b>
- <small>Learn more about the configuration file used by Next.js.</small>
- </a>
-</div>
-
-<div class="card">
- <a href="/docs/deployment.md">
- <b>Deployment:</b>
- <small>Compile and deploy your Next.js app to production.</small>
- </a>
-</div>
diff --git a/docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md b/docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md
index 7b6435c1eba30..20056521d6e78 100644
--- a/docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md
+++ b/docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md
@@ -4,6 +4,13 @@ description: A custom asset prefix allows you serve static assets from a CDN. Le
# CDN Support with Asset Prefix
+> **Attention**: [Deploying to Vercel](/docs/deployment.md) automatically configures a global CDN for your Next.js project.
+> You do not need to manually setup an Asset Prefix.
+
+> **Note**: Next.js 9.5+ added support for a customizable [Base Path](/docs/api-reference/next.config.js/basepath.md), which is better
+> suited for hosting your application on a sub-path like `/docs`.
+> We do not suggest you use a custom Asset Prefix for this use case.
+
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.
Open `next.config.js` and add the `assetPrefix` config:
@@ -17,7 +24,25 @@ module.exports = {
}
```
-Next.js will automatically use your prefix in the scripts it loads, but this has no effect whatsoever on the [public](/docs/basic-features/static-file-serving.md) folder; if you want to serve those assets over a CDN, you'll have to introduce the prefix yourself. One way of introducing a prefix that works inside your components and varies by environment is documented [in this example](https://github.com/zeit/next.js/tree/canary/examples/with-universal-configuration-build-time).
+Next.js will automatically use your asset prefix for the JavaScript and CSS files it loads from the `/_next/` path (`.next/static/` folder). For example, with the above configuration, the following request for a JS chunk:
+
+```
+/_next/static/chunks/4b9b41aaa062cbbfeff4add70f256968c51ece5d.4d708494b3aed70c04f0.js
+```
+
+Would instead become:
+
+```
+https://cdn.mydomain.com/_next/static/chunks/4b9b41aaa062cbbfeff4add70f256968c51ece5d.4d708494b3aed70c04f0.js
+```
+
+The exact configuration for uploading your files to a given CDN will depend on your CDN of choice. The only folder you need to host on your CDN is the contents of `.next/static/`, which should be uploaded as `_next/static/` as the above URL request indicates. **Do not upload the rest of your `.next/` folder**, as you should not expose your server code and other configuration to the public.
+
+While `assetPrefix` covers requests to `_next/static`, it does not influence the following paths:
+
+- Files in the [public](/docs/basic-features/static-file-serving.md) folder; if you want to serve those assets over a CDN, you'll have to introduce the prefix yourself
+- `/_next/data/` requests for `getServerSideProps` pages. These requests will always be made against the main domain since they're not static.
+- `/_next/data/` requests for `getStaticProps` pages. These requests will always be made against the main domain to support [Incremental Static Generation](/docs/basic-features/data-fetching.md#incremental-static-regeneration), even if you're not using it (for consistency).
## Related
diff --git a/docs/api-reference/next.config.js/compression.md b/docs/api-reference/next.config.js/compression.md
index c20ebe798e1c7..6947040d2ec01 100644
--- a/docs/api-reference/next.config.js/compression.md
+++ b/docs/api-reference/next.config.js/compression.md
@@ -4,7 +4,7 @@ description: Next.js provides gzip compression to compress rendered content and
# 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.
+Next.js provides [**gzip**](https://tools.ietf.org/html/rfc6713#section-3) compression to compress rendered content and static files. 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.
To disable **compression**, open `next.config.js` and disable the `compress` config:
diff --git a/docs/api-reference/next.config.js/custom-page-extensions.md b/docs/api-reference/next.config.js/custom-page-extensions.md
index 54fc78f6f9ba3..793228d67fc24 100644
--- a/docs/api-reference/next.config.js/custom-page-extensions.md
+++ b/docs/api-reference/next.config.js/custom-page-extensions.md
@@ -4,16 +4,18 @@ description: Extend the default page extensions used by Next.js when resolving p
# 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.
+Aimed at modules like [@next/mdx](https://github.com/vercel/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.
Open `next.config.js` and add the `pageExtensions` config:
```js
module.exports = {
- pageExtensions: ['mdx', 'jsx', 'js', 'ts', 'tsx'],
+ pageExtensions: ['mdx', 'md', 'jsx', 'js', 'tsx', 'ts'],
}
```
+> **Note**: configuring `pageExtensions` also affects `_document.js`, `_app.js` as well as files under `pages/api/`. For example, setting `pageExtensions: ['page.tsx', 'page.ts']` means the following files: `_document.tsx`, `_app.tsx`, `pages/users.tsx` and `pages/api/users.ts` will have to be renamed to `_document.page.tsx`, `_app.page.tsx`, `pages/users.page.tsx` and `pages/api/users.page.ts` respectively.
+
## Related
<div class="card">
diff --git a/docs/api-reference/next.config.js/custom-webpack-config.md b/docs/api-reference/next.config.js/custom-webpack-config.md
index 5e0f74a565632..6b4535c7e80f5 100644
--- a/docs/api-reference/next.config.js/custom-webpack-config.md
+++ b/docs/api-reference/next.config.js/custom-webpack-config.md
@@ -4,28 +4,25 @@ description: Extend the default webpack config added by Next.js.
# Custom Webpack Config
+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.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.md)
+
Some commonly asked for features are available as plugins:
-- [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass)
-- [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less)
-- [@zeit/next-stylus](https://github.com/zeit/next-plugins/tree/master/packages/next-stylus)
-- [@zeit/next-preact](https://github.com/zeit/next-plugins/tree/master/packages/next-preact)
-- [@next/mdx](https://github.com/zeit/next.js/tree/canary/packages/next-mdx)
-- [@next/bundle-analyzer](https://github.com/zeit/next.js/tree/canary/packages/next-bundle-analyzer)
+- [@next/mdx](https://github.com/vercel/next.js/tree/canary/packages/next-mdx)
+- [@next/bundle-analyzer](https://github.com/vercel/next.js/tree/canary/packages/next-bundle-analyzer)
In order to extend our usage of `webpack`, you can define a function that extends its config inside `next.config.js`, like so:
```js
module.exports = {
webpack: (config, { buildId, dev, isServer, defaultLoaders, webpack }) => {
- // Note: we provide webpack above so you should not `require` it
- // Perform customizations to webpack config
- // Important: return the modified config
- config.plugins.push(new webpack.IgnorePlugin(/\/__tests__\//))
- return config
- },
- webpackDevMiddleware: config => {
- // Perform customizations to webpack dev middleware config
// Important: return the modified config
return config
},
@@ -47,7 +44,7 @@ Example usage of `defaultLoaders.babel`:
```js
// Example config for adding a loader that depends on babel-loader
// This source was taken from the @next/mdx plugin source:
-// https://github.com/zeit/next.js/tree/canary/packages/next-mdx
+// https://github.com/vercel/next.js/tree/canary/packages/next-mdx
module.exports = {
webpack: (config, options) => {
config.module.rules.push({
diff --git a/docs/api-reference/next.config.js/disabling-http-keep-alive.md b/docs/api-reference/next.config.js/disabling-http-keep-alive.md
new file mode 100644
index 0000000000000..bfa79ad3d8b6d
--- /dev/null
+++ b/docs/api-reference/next.config.js/disabling-http-keep-alive.md
@@ -0,0 +1,36 @@
+---
+description: Next.js will automatically use HTTP Keep-Alive by default. Learn more about how to disable HTTP Keep-Alive here.
+---
+
+# Disabling HTTP Keep-Alive
+
+Next.js automatically polyfills [node-fetch](/docs/basic-features/supported-browsers-features#polyfills) and enables [HTTP Keep-Alive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Keep-Alive) by default. You may want to disable HTTP Keep-Alive for certain `fetch()` calls or globally.
+
+For a single `fetch()` call, you can add the agent option:
+
+```js
+import { Agent } from 'https'
+
+const url = 'https://example.com'
+const agent = new Agent({ keepAlive: false })
+fetch(url, { agent })
+```
+
+To override all `fetch()` calls globally, you can use `next.config.js`:
+
+```js
+module.exports = {
+ httpAgentOptions: {
+ keepAlive: false,
+ },
+}
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/disabling-x-powered-by.md b/docs/api-reference/next.config.js/disabling-x-powered-by.md
index 1595d8e300116..29a0810f08eed 100644
--- a/docs/api-reference/next.config.js/disabling-x-powered-by.md
+++ b/docs/api-reference/next.config.js/disabling-x-powered-by.md
@@ -1,10 +1,10 @@
---
-description: Next.js will add `x-powered-by` to the request headers by default. Learn to opt-out of it here.
+description: Next.js will add the `x-powered-by` header by default. Learn to opt-out of it here.
---
# Disabling x-powered-by
-By default Next.js will add `x-powered-by` to the request headers. To opt-out of it, open `next.config.js` and disable the `poweredByHeader` config:
+By default Next.js will add the `x-powered-by` header. To opt-out of it, open `next.config.js` and disable the `poweredByHeader` config:
```js
module.exports = {
diff --git a/docs/api-reference/next.config.js/environment-variables.md b/docs/api-reference/next.config.js/environment-variables.md
index 068d366f491d0..582f1449b60df 100644
--- a/docs/api-reference/next.config.js/environment-variables.md
+++ b/docs/api-reference/next.config.js/environment-variables.md
@@ -4,11 +4,12 @@ description: Learn to add and access environment variables in your Next.js appli
# Environment Variables
+> 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>
<ul>
- <li><a href="/zeit/next.js/tree/canary/examples/with-env-from-next-config-js">With env</a></li>
- <li><a href="/zeit/next.js/tree/canary/examples/with-now-env">With Now env</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/with-env-from-next-config-js">With env</a></li>
</ul>
</details>
@@ -54,3 +55,10 @@ return <h1>The value of customKey is: {'my-value'}</h1>
<small>Learn more about the configuration file used by Next.js.</small>
</a>
</div>
+
+<div class="card">
+ <a href="/docs/basic-features/environment-variables.md">
+ <b>Built-in support for Environment Variables:</b>
+ <small>Learn more about the new support for environment variables.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/exportPathMap.md b/docs/api-reference/next.config.js/exportPathMap.md
index 449f00e038aae..6a5efe93f305c 100644
--- a/docs/api-reference/next.config.js/exportPathMap.md
+++ b/docs/api-reference/next.config.js/exportPathMap.md
@@ -9,10 +9,12 @@ description: Customize the pages that will be exported as HTML files when using
<details>
<summary><b>Examples</b></summary>
<ul>
- <li><a href="/zeit/next.js/tree/canary/examples/with-static-export">Static Export</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/with-static-export">Static Export</a></li>
</ul>
</details>
+`exportPathMap` allows you to specify a mapping of request paths to page destinations, to be used during export. Paths defined in `exportPathMap` will also be available when using [`next dev`](/docs/api-reference/cli.md#development).
+
Let's start with an example, to create a custom `exportPathMap` for an app with the following pages:
- `pages/index.js`
@@ -23,7 +25,7 @@ Open `next.config.js` and add the following `exportPathMap` config:
```js
module.exports = {
- exportPathMap: async function(
+ exportPathMap: async function (
defaultPathMap,
{ dev, dir, outDir, distDir, buildId }
) {
@@ -38,13 +40,15 @@ module.exports = {
}
```
+Note: the `query` field in `exportPathMap` can not be used with [automatically statically optimized pages](/docs/advanced-features/automatic-static-optimization) or [`getStaticProps` pages](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) as they are rendered to HTML files at build-time and additional query information can not be provided during `next export`.
+
The pages will then be exported as HTML files, for example, `/about` will become `/about.html`.
`exportPathMap` is an `async` function that receives 2 arguments: the first one is `defaultPathMap`, which is the default map used by Next.js. The second argument is an object with:
- `dev` - `true` when `exportPathMap` is being called in development. `false` when running `next export`. In development `exportPathMap` is used to define routes.
- `dir` - Absolute path to the project directory
-- `outDir` - Absolute path to the `out/` directory (configurable with `-o`). When `dev` is `true` the value of `outDir` will be `null`.
+- `outDir` - Absolute path to the `out/` directory ([configurable with `-o`](#customizing-the-output-directory)). When `dev` is `true` the value of `outDir` will be `null`.
- `distDir` - Absolute path to the `.next/` directory (configurable with the [`distDir`](/docs/api-reference/next.config.js/setting-a-custom-build-directory.md) config)
- `buildId` - The generated build id
@@ -59,14 +63,22 @@ The returned object is a map of pages where the `key` is the `pathname` and the
It is possible to configure Next.js to export pages as `index.html` files and require trailing slashes, `/about` becomes `/about/index.html` and is routable via `/about/`. This was the default behavior prior to Next.js 9.
-To switch back and add a trailing slash, open `next.config.js` and enable the `exportTrailingSlash` config:
+To switch back and add a trailing slash, open `next.config.js` and enable the `trailingSlash` config:
```js
module.exports = {
- exportTrailingSlash: true,
+ trailingSlash: true,
}
```
+## Customizing the output directory
+
+[`next export`](/docs/advanced-features/static-html-export.md#how-to-use-it) will use `out` as the default output directory, you can customize this using the `-o` argument, like so:
+
+```bash
+next export -o outdir
+```
+
## Related
<div class="card">
diff --git a/docs/api-reference/next.config.js/headers.md b/docs/api-reference/next.config.js/headers.md
new file mode 100644
index 0000000000000..d64c01c676b79
--- /dev/null
+++ b/docs/api-reference/next.config.js/headers.md
@@ -0,0 +1,390 @@
+---
+description: Add custom HTTP headers to your Next.js app.
+---
+
+# Headers
+
+<details open>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="/vercel/next.js/tree/canary/examples/headers">Headers</a></li>
+ </ul>
+</details>
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| --------- | -------------- |
+| `v10.2.0` | `has` added. |
+| `v9.5.0` | Headers added. |
+
+</details>
+
+Headers allow you to set custom HTTP headers for an incoming request path.
+
+To set custom HTTP headers you can use the `headers` key in `next.config.js`:
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ {
+ source: '/about',
+ headers: [
+ {
+ key: 'x-custom-header',
+ value: 'my custom header value',
+ },
+ {
+ key: 'x-another-custom-header',
+ value: 'my other custom header value',
+ },
+ ],
+ },
+ ]
+ },
+}
+```
+
+`headers` is an async function that expects an array to be returned holding objects with `source` and `headers` properties:
+
+- `source` is the incoming request path pattern.
+- `headers` is an array of header objects with the `key` and `value` properties.
+- `basePath`: `false` or `undefined` - if false the basePath won't be included when matching, can be used for external rewrites only.
+- `locale`: `false` or `undefined` - whether the locale should not be included when matching.
+- `has` is an array of [has objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties.
+
+Headers are checked before the filesystem which includes pages and `/public` files.
+
+## Header Overriding Behavior
+
+If two headers match the same path and set the same header key, the last header key will override the first. Using the below headers, the path `/hello` will result in the header `x-hello` being `world` due to the last header value set being `world`.
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ {
+ source: '/:path*',
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'there',
+ },
+ ],
+ },
+ {
+ source: '/hello',
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'world',
+ },
+ ],
+ },
+ ],
+ },
+}
+```
+
+## Path Matching
+
+Path matches are allowed, for example `/blog/:slug` will match `/blog/hello-world` (no nested paths):
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ {
+ source: '/blog/:slug',
+ headers: [
+ {
+ key: 'x-slug',
+ value: ':slug', // Matched parameters can be used in the value
+ },
+ {
+ key: 'x-slug-:slug', // Matched parameters can be used in the key
+ value: 'my other custom header value',
+ },
+ ],
+ },
+ ],
+ },
+}
+```
+
+### Wildcard Path Matching
+
+To match a wildcard path you can use `*` after a parameter, for example `/blog/:slug*` will match `/blog/a/b/c/d/hello-world`:
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ {
+ source: '/blog/:slug*',
+ headers: [
+ {
+ key: 'x-slug',
+ value: ':slug*', // Matched parameters can be used in the value
+ },
+ {
+ key: 'x-slug-:slug*', // Matched parameters can be used in the key
+ value: 'my other custom header value',
+ },
+ ],
+ },
+ ],
+ },
+}
+```
+
+### Regex Path Matching
+
+To match a regex path you can wrap the regex in parenthesis after a parameter, for example `/blog/:slug(\\d{1,})` will match `/blog/123` but not `/blog/abc`:
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ {
+ source: '/blog/:post(\\d{1,})',
+ headers: [
+ {
+ key: 'x-post',
+ value: ':post',
+ },
+ ],
+ },
+ ],
+ },
+}
+```
+
+The following characters `(`, `)`, `{`, `}`, `:`, `*`, `+`, `?` are used for regex path matching, so when used in the `source` as non-special values they must be escaped by adding `\\` before them:
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ {
+ // this will match `/english(default)/something` being requested
+ source: '/english\\(default\\)/:slug',
+ headers: [
+ {
+ key: 'x-header',
+ value: 'value',
+ },
+ ],
+ },
+ ]
+ },
+}
+```
+
+## Header, Cookie, and Query Matching
+
+To only apply a header when either header, cookie, or query values also match the `has` field can be used. Both the `source` and all `has` items must match for the header to be applied.
+
+`has` items have the following fields:
+
+- `type`: `String` - must be either `header`, `cookie`, `host`, or `query`.
+- `key`: `String` - the key from the selected type to match against.
+- `value`: `String` or `undefined` - the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value `first-(?<paramName>.*)` is used for `first-second` then `second` will be usable in the destination with `:paramName`.
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ // if the header `x-add-header` is present,
+ // the `x-another-header` header will be applied
+ {
+ source: '/:path*',
+ has: [
+ {
+ type: 'header',
+ key: 'x-add-header',
+ },
+ ],
+ headers: [
+ {
+ key: 'x-another-header',
+ value: 'hello',
+ },
+ ],
+ },
+ // if the source, query, and cookie are matched,
+ // the `x-authorized` header will be applied
+ {
+ source: '/specific/:path*',
+ has: [
+ {
+ type: 'query',
+ key: 'page',
+ // the page value will not be available in the
+ // header key/values since value is provided and
+ // doesn't use a named capture group e.g. (?<page>home)
+ value: 'home',
+ },
+ {
+ type: 'cookie',
+ key: 'authorized',
+ value: 'true',
+ },
+ ],
+ headers: [
+ {
+ key: 'x-authorized',
+ value: ':authorized',
+ },
+ ],
+ },
+ // if the header `x-authorized` is present and
+ // contains a matching value, the `x-another-header` will be applied
+ {
+ source: '/:path*',
+ has: [
+ {
+ type: 'header',
+ key: 'x-authorized',
+ value: '(?<authorized>yes|true)',
+ },
+ ],
+ headers: [
+ {
+ key: 'x-another-header',
+ value: ':authorized',
+ },
+ ],
+ },
+ // if the host is `example.com`,
+ // this header will be applied
+ {
+ source: '/:path*',
+ has: [
+ {
+ type: 'host',
+ value: 'example.com',
+ },
+ ],
+ headers: [
+ {
+ key: 'x-another-header',
+ value: ':authorized',
+ },
+ ],
+ },
+ ]
+ },
+}
+```
+
+### 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,
+ },
+ ]
+ },
+}
+```
+
+### Headers with i18n support
+
+When leveraging [`i18n` support](/docs/advanced-features/i18n-routing.md) with headers each `source` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the header. If `locale: false` is used you must prefix the `source` with a locale for it to be matched correctly.
+
+```js
+module.exports = {
+ i18n: {
+ locales: ['en', 'fr', 'de'],
+ defaultLocale: 'en',
+ },
+
+ async headers() {
+ return [
+ {
+ source: '/with-locale', // automatically handles all locales
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'world',
+ },
+ ],
+ },
+ {
+ // does not handle locales automatically since locale: false is set
+ source: '/nl/with-locale-manual',
+ locale: false,
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'world',
+ },
+ ],
+ },
+ {
+ // this matches '/' since `en` is the defaultLocale
+ source: '/en',
+ locale: false,
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'world',
+ },
+ ],
+ },
+ {
+ // this gets converted to /(en|fr|de)/(.*) so will not match the top-level
+ // `/` or `/fr` routes like /:path* would
+ source: '/(.*)',
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'worlld',
+ },
+ ],
+ },
+ ]
+ },
+}
+```
+
+### Cache-Control
+
+Cache-Control headers set in next.config.js will be overwritten in production to ensure that static assets can be cached effectively. If you need to revalidate the cache of a page that has been [statically generated](https://nextjs.org/docs/basic-features/pages#static-generation-recommended), you can do so by setting `revalidate` in the page's [`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) function.
+
+## Related
+
+For more information, we recommend the following sections:
+
+<div class="card">
+ <a href="/docs/advanced-features/security-headers.md">
+ <b>Security Headers:</b>
+ <small>Improve the security of your Next.js application by add HTTP response headers.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/ignoring-eslint.md b/docs/api-reference/next.config.js/ignoring-eslint.md
new file mode 100644
index 0000000000000..650c678bfd072
--- /dev/null
+++ b/docs/api-reference/next.config.js/ignoring-eslint.md
@@ -0,0 +1,37 @@
+---
+description: Next.js reports ESLint errors and warnings during builds by default. Learn how to opt-out of this behavior here.
+---
+
+# Ignoring ESLint
+
+When ESLint is detected in your project, Next.js fails your **production build** (`next build`) when errors are present.
+
+If you'd like Next.js to produce production code even when your application has ESLint errors, you can disable the built-in linting step completely. This is not recommended unless you already have ESLint configured to run in a separate part of your workflow (for example, in CI or a pre-commit hook).
+
+Open `next.config.js` and enable the `ignoreDuringBuilds` option in the `eslint` config:
+
+```js
+module.exports = {
+ eslint: {
+ // Warning: This allows production builds to successfully complete even if
+ // your project has ESLint errors.
+ ignoreDuringBuilds: true,
+ },
+}
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/basic-features/eslint.md">
+ <b>ESLint:</b>
+ <small>Get started with ESLint in Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/ignoring-typescript-errors.md b/docs/api-reference/next.config.js/ignoring-typescript-errors.md
index f9f5b6ba9e4f4..57335b30cf8ce 100644
--- a/docs/api-reference/next.config.js/ignoring-typescript-errors.md
+++ b/docs/api-reference/next.config.js/ignoring-typescript-errors.md
@@ -4,23 +4,9 @@ description: Next.js reports TypeScript errors by default. Learn to opt-out of t
# Ignoring TypeScript Errors
-Next.js reports TypeScript errors by default. If you don't want to leverage this behavior and prefer something else instead, like your editor's integration, you may want to disable it.
+Next.js fails your **production build** (`next build`) when TypeScript errors are present in your project.
-Open `next.config.js` and enable the `ignoreDevErrors` option in the `typescript` config:
-
-```js
-module.exports = {
- typescript: {
- ignoreDevErrors: true,
- },
-}
-```
-
-Next.js will still fail your **production build** (`next build`) when TypeScript errors are present in your project.
-
----
-
-If you'd like Next.js to dangerously produce production code even when your application has errors, you can also disable error reports for builds.
+If you'd like Next.js to dangerously produce production code even when your application has errors, you can disable the built-in type checking step.
> Be sure you are running type checks as part of your build or deploy process, otherwise this can be very dangerous.
@@ -32,9 +18,6 @@ module.exports = {
// !! WARN !!
// Dangerously allow production builds to successfully complete even if
// your project has type errors.
- //
- // This option is rarely needed, and should be reserved for advanced
- // setups. You may be looking for `ignoreDevErrors` instead.
// !! WARN !!
ignoreBuildErrors: true,
},
diff --git a/docs/api-reference/next.config.js/introduction.md b/docs/api-reference/next.config.js/introduction.md
index e9fd3f681694f..02bf1c5904bbf 100644
--- a/docs/api-reference/next.config.js/introduction.md
+++ b/docs/api-reference/next.config.js/introduction.md
@@ -11,22 +11,31 @@ For custom advanced behavior of Next.js, you can create a `next.config.js` in th
Take a look at the following `next.config.js` example:
```js
-module.exports = {
+/**
+ * @type {import('next').NextConfig}
+ */
+const nextConfig = {
/* config options here */
}
+
+module.exports = nextConfig
```
You can also use a function:
```js
module.exports = (phase, { defaultConfig }) => {
- return {
+ /**
+ * @type {import('next').NextConfig}
+ */
+ const nextConfig = {
/* config options here */
}
+ return nextConfig
}
```
-`phase` is the current context in which the configuration is loaded. You can see the available phases [here](https://github.com/zeit/next.js/blob/canary/packages/next/next-server/lib/constants.ts#L1-L4). Phases can be imported from `next/constants`:
+`phase` is the current context in which the configuration is loaded. You can see the [available phases](https://github.com/vercel/next.js/blob/canary/packages/next/shared/lib/constants.ts#L1-L4). Phases can be imported from `next/constants`:
```js
const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')
@@ -44,8 +53,8 @@ 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/zeit/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 in this file](https://github.com/vercel/next.js/blob/canary/packages/next/server/config-shared.ts#L68).
-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.
+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.
> Avoid using new JavaScript features not available in your target Node.js version. `next.config.js` will not be parsed by Webpack, Babel or TypeScript.
diff --git a/docs/api-reference/next.config.js/react-strict-mode.md b/docs/api-reference/next.config.js/react-strict-mode.md
new file mode 100644
index 0000000000000..d442b81ac1ad0
--- /dev/null
+++ b/docs/api-reference/next.config.js/react-strict-mode.md
@@ -0,0 +1,29 @@
+---
+description: The complete Next.js runtime is now Strict Mode-compliant, learn how to opt-in
+---
+
+# React Strict Mode
+
+> **Suggested**: We strongly suggest you enable Strict Mode in your Next.js application to better prepare your application for the future of React.
+
+The Next.js runtime is now Strict Mode-compliant. To opt-in to Strict Mode, configure the following option in your `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+ reactStrictMode: true,
+}
+```
+
+If you or your team are not ready to use Strict Mode in your entire application, that's OK! You can incrementally migrate on a page-by-page basis [using `<React.StrictMode>`](https://reactjs.org/docs/strict-mode.html).
+
+React's Strict Mode is a development mode only feature for highlighting potential problems in an application. It helps to identify unsafe lifecycles, legacy API usage, and a number of other features.
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/redirects.md b/docs/api-reference/next.config.js/redirects.md
new file mode 100644
index 0000000000000..9d35b97c34506
--- /dev/null
+++ b/docs/api-reference/next.config.js/redirects.md
@@ -0,0 +1,294 @@
+---
+description: Add redirects to your Next.js app.
+---
+
+# Redirects
+
+<details open>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="/vercel/next.js/tree/canary/examples/redirects">Redirects</a></li>
+ </ul>
+</details>
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| --------- | ---------------- |
+| `v10.2.0` | `has` added. |
+| `v9.5.0` | Redirects added. |
+
+</details>
+
+Redirects allow you to redirect an incoming request path to a different destination path.
+
+Redirects are only available on the Node.js environment and do not affect client-side routing.
+
+To use Redirects you can use the `redirects` key in `next.config.js`:
+
+```js
+module.exports = {
+ async redirects() {
+ return [
+ {
+ source: '/about',
+ destination: '/',
+ permanent: true,
+ },
+ ]
+ },
+}
+```
+
+`redirects` is an async function that expects an array to be returned holding objects with `source`, `destination`, and `permanent` properties:
+
+- `source` is the incoming request path pattern.
+- `destination` is the path you want to route to.
+- `permanent` if the redirect is permanent or not.
+- `basePath`: `false` or `undefined` - if false the basePath won't be included when matching, can be used for external rewrites only.
+- `locale`: `false` or `undefined` - whether the locale should not be included when matching.
+- `has` is an array of [has objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties.
+
+Redirects are checked before the filesystem which includes pages and `/public` files.
+
+When a redirect is applied, any query values provided in the request will be passed through to the redirect destination. For example, see the following redirect configuration:
+
+```js
+{
+ source: '/old-blog/:path*',
+ destination: '/blog/:path*',
+ permanent: false
+}
+```
+
+When `/old-blog/post-1?hello=world` is requested, the client will be redirected to `/blog/post-1?hello=world`.
+
+## Path Matching
+
+Path matches are allowed, for example `/old-blog/:slug` will match `/old-blog/hello-world` (no nested paths):
+
+```js
+module.exports = {
+ async redirects() {
+ return [
+ {
+ source: '/old-blog/:slug',
+ destination: '/news/:slug', // Matched parameters can be used in the destination
+ permanent: true,
+ },
+ ]
+ },
+}
+```
+
+### Wildcard Path Matching
+
+To match a wildcard path you can use `*` after a parameter, for example `/blog/:slug*` will match `/blog/a/b/c/d/hello-world`:
+
+```js
+module.exports = {
+ async redirects() {
+ return [
+ {
+ source: '/blog/:slug*',
+ destination: '/news/:slug*', // Matched parameters can be used in the destination
+ permanent: true,
+ },
+ ]
+ },
+}
+```
+
+### Regex Path Matching
+
+To match a regex path you can wrap the regex in parentheses after a parameter, for example `/post/:slug(\\d{1,})` will match `/post/123` but not `/post/abc`:
+
+```js
+module.exports = {
+ async redirects() {
+ return [
+ {
+ source: '/post/:slug(\\d{1,})',
+ destination: '/news/:slug', // Matched parameters can be used in the destination
+ permanent: false,
+ },
+ ]
+ },
+}
+```
+
+The following characters `(`, `)`, `{`, `}`, `:`, `*`, `+`, `?` are used for regex path matching, so when used in the `source` as non-special values they must be escaped by adding `\\` before them:
+
+```js
+module.exports = {
+ async redirects() {
+ return [
+ {
+ // this will match `/english(default)/something` being requested
+ source: '/english\\(default\\)/:slug',
+ destination: '/en-us/:slug',
+ permanent: false,
+ },
+ ]
+ },
+}
+```
+
+## Header, Cookie, and Query Matching
+
+To only match a redirect when header, cookie, or query values also match the `has` field can be used. Both the `source` and all `has` items must match for the redirect to be applied.
+
+`has` items have the following fields:
+
+- `type`: `String` - must be either `header`, `cookie`, `host`, or `query`.
+- `key`: `String` - the key from the selected type to match against.
+- `value`: `String` or `undefined` - the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value `first-(?<paramName>.*)` is used for `first-second` then `second` will be usable in the destination with `:paramName`.
+
+```js
+module.exports = {
+ async redirects() {
+ return [
+ // if the header `x-redirect-me` is present,
+ // this redirect will be applied
+ {
+ source: '/:path((?!another-page$).*)',
+ has: [
+ {
+ type: 'header',
+ key: 'x-redirect-me',
+ },
+ ],
+ permanent: false,
+ destination: '/another-page',
+ },
+ // if the source, query, and cookie are matched,
+ // this redirect will be applied
+ {
+ source: '/specific/:path*',
+ has: [
+ {
+ type: 'query',
+ key: 'page',
+ // the page value will not be available in the
+ // destination since value is provided and doesn't
+ // use a named capture group e.g. (?<page>home)
+ value: 'home',
+ },
+ {
+ type: 'cookie',
+ key: 'authorized',
+ value: 'true',
+ },
+ ],
+ permanent: false,
+ destination: '/another/:path*',
+ },
+ // if the header `x-authorized` is present and
+ // contains a matching value, this redirect will be applied
+ {
+ source: '/',
+ has: [
+ {
+ type: 'header',
+ key: 'x-authorized',
+ value: '(?<authorized>yes|true)',
+ },
+ ],
+ permanent: false,
+ destination: '/home?authorized=:authorized',
+ },
+ // if the host is `example.com`,
+ // this redirect will be applied
+ {
+ source: '/:path((?!another-page$).*)',,
+ has: [
+ {
+ type: 'host',
+ value: 'example.com',
+ },
+ ],
+ destination: '/another-page',
+ },
+ ]
+ },
+}
+```
+
+### 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,
+ },
+ ]
+ },
+}
+```
+
+### Redirects with i18n support
+
+When leveraging [`i18n` support](/docs/advanced-features/i18n-routing.md) with redirects each `source` and `destination` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the redirect. If `locale: false` is used you must prefix the `source` and `destination` with a locale for it to be matched correctly.
+
+```js
+module.exports = {
+ i18n: {
+ locales: ['en', 'fr', 'de'],
+ defaultLocale: 'en',
+ },
+
+ async redirects() {
+ return [
+ {
+ source: '/with-locale', // automatically handles all locales
+ destination: '/another', // automatically passes the locale on
+ permanent: false,
+ },
+ {
+ // does not handle locales automatically since locale: false is set
+ source: '/nl/with-locale-manual',
+ destination: '/nl/another',
+ locale: false,
+ permanent: false,
+ },
+ {
+ // this matches '/' since `en` is the defaultLocale
+ source: '/en',
+ destination: '/en/another',
+ locale: false,
+ permanent: false,
+ },
+ {
+ // this gets converted to /(en|fr|de)/(.*) so will not match the top-level
+ // `/` or `/fr` routes like /:path* would
+ source: '/(.*)',
+ destination: '/another',
+ permanent: false,
+ },
+ ]
+ },
+}
+```
+
+In some rare cases, you might need to assign a custom status code for older HTTP Clients to properly redirect. In these cases, you can use the `statusCode` property instead of the `permanent` property, but not both. Note: to ensure IE11 compatibility a `Refresh` header is automatically added for the 308 status code.
+
+## Other Redirects
+
+- Inside [API Routes](/docs/api-routes/response-helpers.md), you can use `res.redirect()`.
+- Inside [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) and [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering), you can redirect specific pages at request-time.
diff --git a/docs/api-reference/next.config.js/rewrites.md b/docs/api-reference/next.config.js/rewrites.md
new file mode 100644
index 0000000000000..46c58eb6035dd
--- /dev/null
+++ b/docs/api-reference/next.config.js/rewrites.md
@@ -0,0 +1,406 @@
+---
+description: Add rewrites to your Next.js app.
+---
+
+# Rewrites
+
+<details open>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="/vercel/next.js/tree/canary/examples/rewrites">Rewrites</a></li>
+ </ul>
+</details>
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| --------- | --------------- |
+| `v10.2.0` | `has` added. |
+| `v9.5.0` | Rewrites added. |
+
+</details>
+
+Rewrites allow you to map an incoming request path to a different destination path.
+
+Rewrites act as a URL proxy and mask the destination path, making it appear the user hasn't changed their location on the site. In contrast, [redirects](/docs/api-reference/next.config.js/redirects.md) will reroute to a new page and show the URL changes.
+
+To use rewrites you can use the `rewrites` key in `next.config.js`:
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/about',
+ destination: '/',
+ },
+ ]
+ },
+}
+```
+
+Rewrites are applied to client-side routing, a `<Link href="/about">` will have the rewrite applied in the above example.
+
+`rewrites` is an async function that expects an array to be returned holding objects with `source` and `destination` properties:
+
+- `source`: `String` - is the incoming request path pattern.
+- `destination`: `String` is the path you want to route to.
+- `basePath`: `false` or `undefined` - if false the basePath won't be included when matching, can be used for external rewrites only.
+- `locale`: `false` or `undefined` - whether the locale should not be included when matching.
+- `has` is an array of [has objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties.
+
+Rewrites are applied after checking the filesystem (pages and `/public` files) and before dynamic routes by default. This behavior can be changed by instead returning an object instead of an array from the `rewrites` function since `v10.1` of Next.js:
+
+```js
+module.exports = {
+ async rewrites() {
+ return {
+ beforeFiles: [
+ // These rewrites are checked after headers/redirects
+ // and before all files including _next/public files which
+ // allows overriding page files
+ {
+ source: '/some-page',
+ destination: '/somewhere-else',
+ has: [{ type: 'query', key: 'overrideMe' }],
+ },
+ ],
+ afterFiles: [
+ // These rewrites are checked after pages/public files
+ // are checked but before dynamic routes
+ {
+ source: '/non-existent',
+ destination: '/somewhere-else',
+ },
+ ],
+ fallback: [
+ // These rewrites are checked after both pages/public files
+ // and dynamic routes are checked
+ {
+ source: '/:path*',
+ destination: `https://my-old-site.com/:path*`,
+ },
+ ],
+ }
+ },
+}
+```
+
+Note: rewrites in `beforeFiles` do not check the filesystem/dynamic routes immediately after matching a source, they continue until all `beforeFiles` have been checked.
+
+The order Next.js routes are checked is:
+
+1. [headers](/docs/api-reference/next.config.js/headers) are checked/applied
+2. [redirects](/docs/api-reference/next.config.js/redirects) are checked/applied
+3. `beforeFiles` rewrites are checked/applied
+4. static files from the [public directory](/docs/basic-features/static-file-serving), `_next/static` files, and non-dynamic pages are checked/served
+5. `afterFiles` rewrites are checked/applied, if one of these rewrites is matched we check dynamic routes/static files after each match
+6. `fallback` rewrites are checked/applied, these are applied before rendering the 404 page and after dynamic routes/all static assets have been checked.
+
+## Rewrite parameters
+
+When using parameters in a rewrite the parameters will be passed in the query by default when none of the parameters are used in the `destination`.
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/old-about/:path*',
+ destination: '/about', // The :path parameter isn't used here so will be automatically passed in the query
+ },
+ ]
+ },
+}
+```
+
+If a parameter is used in the destination none of the parameters will be automatically passed in the query.
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/docs/:path*',
+ destination: '/:path*', // The :path parameter is used here so will not be automatically passed in the query
+ },
+ ]
+ },
+}
+```
+
+You can still pass the parameters manually in the query if one is already used in the destination by specifying the query in the `destination`.
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/:first/:second',
+ destination: '/:first?second=:second',
+ // Since the :first parameter is used in the destination the :second parameter
+ // will not automatically be added in the query although we can manually add it
+ // as shown above
+ },
+ ]
+ },
+}
+```
+
+## Path Matching
+
+Path matches are allowed, for example `/blog/:slug` will match `/blog/hello-world` (no nested paths):
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/blog/:slug',
+ destination: '/news/:slug', // Matched parameters can be used in the destination
+ },
+ ]
+ },
+}
+```
+
+### Wildcard Path Matching
+
+To match a wildcard path you can use `*` after a parameter, for example `/blog/:slug*` will match `/blog/a/b/c/d/hello-world`:
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/blog/:slug*',
+ destination: '/news/:slug*', // Matched parameters can be used in the destination
+ },
+ ]
+ },
+}
+```
+
+### Regex Path Matching
+
+To match a regex path you can wrap the regex in parenthesis after a parameter, for example `/blog/:slug(\\d{1,})` will match `/blog/123` but not `/blog/abc`:
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/old-blog/:post(\\d{1,})',
+ destination: '/blog/:post', // Matched parameters can be used in the destination
+ },
+ ]
+ },
+}
+```
+
+The following characters `(`, `)`, `{`, `}`, `:`, `*`, `+`, `?` are used for regex path matching, so when used in the `source` as non-special values they must be escaped by adding `\\` before them:
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ // this will match `/english(default)/something` being requested
+ source: '/english\\(default\\)/:slug',
+ destination: '/en-us/:slug',
+ },
+ ]
+ },
+}
+```
+
+## Header, Cookie, and Query Matching
+
+To only match a rewrite when header, cookie, or query values also match the `has` field can be used. Both the `source` and all `has` items must match for the rewrite to be applied.
+
+`has` items have the following fields:
+
+- `type`: `String` - must be either `header`, `cookie`, `host`, or `query`.
+- `key`: `String` - the key from the selected type to match against.
+- `value`: `String` or `undefined` - the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value `first-(?<paramName>.*)` is used for `first-second` then `second` will be usable in the destination with `:paramName`.
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ // if the header `x-rewrite-me` is present,
+ // this rewrite will be applied
+ {
+ source: '/:path*',
+ has: [
+ {
+ type: 'header',
+ key: 'x-rewrite-me',
+ },
+ ],
+ destination: '/another-page',
+ },
+ // if the source, query, and cookie are matched,
+ // this rewrite will be applied
+ {
+ source: '/specific/:path*',
+ has: [
+ {
+ type: 'query',
+ key: 'page',
+ // the page value will not be available in the
+ // destination since value is provided and doesn't
+ // use a named capture group e.g. (?<page>home)
+ value: 'home',
+ },
+ {
+ type: 'cookie',
+ key: 'authorized',
+ value: 'true',
+ },
+ ],
+ destination: '/:path*/home',
+ },
+ // if the header `x-authorized` is present and
+ // contains a matching value, this rewrite will be applied
+ {
+ source: '/:path*',
+ has: [
+ {
+ type: 'header',
+ key: 'x-authorized',
+ value: '(?<authorized>yes|true)',
+ },
+ ],
+ destination: '/home?authorized=:authorized',
+ },
+ // if the host is `example.com`,
+ // this rewrite will be applied
+ {
+ source: '/:path*',
+ has: [
+ {
+ type: 'host',
+ value: 'example.com',
+ },
+ ],
+ destination: '/another-page',
+ },
+ ]
+ },
+}
+```
+
+## Rewriting to an external URL
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="/vercel/next.js/tree/canary/examples/custom-routes-proxying">Incremental adoption of Next.js</a></li>
+ </ul>
+</details>
+
+Rewrites allow you to rewrite to an external url. This is especially useful for incrementally adopting Next.js.
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/blog/:slug',
+ destination: 'https://example.com/blog/:slug', // Matched parameters can be used in the destination
+ },
+ ]
+ },
+}
+```
+
+### Incremental adoption of Next.js
+
+You can also have Next.js fall back to proxying to an existing website after checking all Next.js routes.
+
+This way you don't have to change the rewrites configuration when migrating more pages to Next.js
+
+```js
+module.exports = {
+ async rewrites() {
+ return {
+ fallback: [
+ {
+ source: '/:path*',
+ destination: `https://custom-routes-proxying-endpoint.vercel.app/:path*`,
+ },
+ ],
+ }
+ },
+}
+```
+
+See additional information on incremental adoption [in the docs here](/docs/migrating/incremental-adoption.md).
+
+### 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 to /without-basePath since basePath: false is set
+ // Note: this can not be used for internal rewrites e.g. `destination: '/another'`
+ source: '/without-basePath',
+ destination: 'https://example.com',
+ basePath: false,
+ },
+ ]
+ },
+}
+```
+
+### Rewrites with i18n support
+
+When leveraging [`i18n` support](/docs/advanced-features/i18n-routing.md) with rewrites each `source` and `destination` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the rewrite. If `locale: false` is used you must prefix the `source` and `destination` with a locale for it to be matched correctly.
+
+```js
+module.exports = {
+ i18n: {
+ locales: ['en', 'fr', 'de'],
+ defaultLocale: 'en',
+ },
+
+ async rewrites() {
+ return [
+ {
+ source: '/with-locale', // automatically handles all locales
+ destination: '/another', // automatically passes the locale on
+ },
+ {
+ // does not handle locales automatically since locale: false is set
+ source: '/nl/with-locale-manual',
+ destination: '/nl/another',
+ locale: false,
+ },
+ {
+ // this matches '/' since `en` is the defaultLocale
+ source: '/en',
+ destination: '/en/another',
+ locale: false,
+ },
+ {
+ // this gets converted to /(en|fr|de)/(.*) so will not match the top-level
+ // `/` or `/fr` routes like /:path* would
+ source: '/(.*)',
+ destination: '/another',
+ },
+ ]
+ },
+}
+```
diff --git a/docs/api-reference/next.config.js/runtime-configuration.md b/docs/api-reference/next.config.js/runtime-configuration.md
index 4a4a2a5ace6e1..27ed9919542b2 100644
--- a/docs/api-reference/next.config.js/runtime-configuration.md
+++ b/docs/api-reference/next.config.js/runtime-configuration.md
@@ -4,9 +4,7 @@ description: Add client and server runtime configuration to your Next.js app.
# Runtime Configuration
-> Generally you'll want to use [build-time environment variables](/docs/api-reference/next.config.js/environment-variables.md) to provide your configuration. The reason for this is that runtime configuration adds rendering / initialization overhead and is incompatible with [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).
-
-> Runtime configuration is not available when using the [`serverless` target](/docs/api-reference/next.config.js/build-target.md#serverless-target).
+> Generally you'll want to use [build-time environment variables](/docs/basic-features/environment-variables.md) to provide your configuration. The reason for this is that runtime configuration adds rendering / initialization overhead and is incompatible with [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).
To add runtime configuration to your app open `next.config.js` and add the `publicRuntimeConfig` and `serverRuntimeConfig` configs:
@@ -34,6 +32,7 @@ To get access to the runtime configs in your app use `next/config`, like so:
```jsx
import getConfig from 'next/config'
+import Image from 'next/image'
// Only holds serverRuntimeConfig and publicRuntimeConfig
const { serverRuntimeConfig, publicRuntimeConfig } = getConfig()
@@ -45,7 +44,11 @@ console.log(publicRuntimeConfig.staticFolder)
function MyImage() {
return (
<div>
- <img src={`${publicRuntimeConfig.staticFolder}/logo.png`} alt="logo" />
+ <Image
+ src={`${publicRuntimeConfig.staticFolder}/logo.png`}
+ alt="logo"
+ layout="fill"
+ />
</div>
)
}
diff --git a/docs/api-reference/next.config.js/static-optimization-indicator.md b/docs/api-reference/next.config.js/static-optimization-indicator.md
index 7ef296f9c36f9..f8c512d388a44 100644
--- a/docs/api-reference/next.config.js/static-optimization-indicator.md
+++ b/docs/api-reference/next.config.js/static-optimization-indicator.md
@@ -4,6 +4,8 @@ description: Optimized pages include an indicator to let you know if it's being
# Static Optimization Indicator
+> **Note:** This indicator was removed in Next.js version 10.0.1. We recommend upgrading to the latest version of Next.js.
+
When a page qualifies for [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) we show an indicator to let you know.
This is helpful since automatic static optimization can be very beneficial and knowing immediately in development if the page qualifies can be useful.
@@ -17,19 +19,3 @@ module.exports = {
},
}
```
-
-## Related
-
-<div class="card">
- <a href="/docs/api-reference/next.config.js/introduction.md">
- <b>Introduction to next.config.js:</b>
- <small>Learn more about the configuration file used by Next.js.</small>
- </a>
-</div>
-
-<div class="card">
- <a href="/docs/advanced-features/automatic-static-optimization.md">
- <b>Automatic Static Optimization:</b>
- <small>Next.js automatically optimizes your app to be static HTML whenever possible. Learn how it works here.</small>
- </a>
-</div>
diff --git a/docs/api-reference/next.config.js/trailing-slash.md b/docs/api-reference/next.config.js/trailing-slash.md
new file mode 100644
index 0000000000000..ee2757f872ccc
--- /dev/null
+++ b/docs/api-reference/next.config.js/trailing-slash.md
@@ -0,0 +1,35 @@
+---
+description: Configure Next.js pages to resolve with or without a trailing slash.
+---
+
+# Trailing Slash
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| -------- | --------------------- |
+| `v9.5.0` | Trailing Slash added. |
+
+</details>
+
+By default Next.js will redirect urls with trailing slashes to their counterpart without a trailing slash. For example `/about/` will redirect to `/about`. You can configure this behavior to act the opposite way, where urls without trailing slashes are redirected to their counterparts with trailing slashes.
+
+Open `next.config.js` and add the `trailingSlash` config:
+
+```js
+module.exports = {
+ trailingSlash: true,
+}
+```
+
+With this option set, urls like `/about` will redirect to `/about/`.
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next/amp.md b/docs/api-reference/next/amp.md
index a5fd080b2fd5d..6cc212791168d 100644
--- a/docs/api-reference/next/amp.md
+++ b/docs/api-reference/next/amp.md
@@ -7,11 +7,11 @@ description: Enable AMP in a page, and control the way Next.js adds AMP to the p
<details>
<summary><b>Examples</b></summary>
<ul>
- <li><a href="/zeit/next.js/tree/canary/examples/amp">AMP</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/amp">AMP</a></li>
</ul>
</details>
-> AMP support is one of our advanced features, you can read more about it [here](/docs/advanced-features/amp-support/introduction.md).
+> AMP support is one of our advanced features, you can [read more about AMP here](/docs/advanced-features/amp-support/introduction.md).
To enable AMP, add the following config to your page:
@@ -22,7 +22,7 @@ export const config = { amp: true }
The `amp` config accepts the following values:
- `true` - The page will be AMP-only
-- `'hybrid'` - The page will two versions, one with AMP and another one with HTML
+- `'hybrid'` - The page will have two versions, one with AMP and another one with HTML
To learn more about the `amp` config, read the sections below.
@@ -44,7 +44,7 @@ The page above is an AMP-only page, which means:
- The page has no Next.js or React client-side runtime
- The page is automatically optimized with [AMP Optimizer](https://github.com/ampproject/amp-toolbox/tree/master/packages/optimizer), an optimizer that applies the same transformations as AMP caches (improves performance by up to 42%)
-- The page has an user-accessible (optimized) version of the page and a search-engine indexable (unoptimized) version of the page
+- The page has a user-accessible (optimized) version of the page and a search-engine indexable (unoptimized) version of the page
## Hybrid AMP Page
diff --git a/docs/api-reference/next/head.md b/docs/api-reference/next/head.md
index 961f18e2b5e00..63010ff4e0643 100644
--- a/docs/api-reference/next/head.md
+++ b/docs/api-reference/next/head.md
@@ -7,8 +7,8 @@ description: Add custom elements to the `head` of your page with the built-in He
<details>
<summary><b>Examples</b></summary>
<ul>
- <li><a href="/zeit/next.js/tree/canary/examples/head-elements">Head Elements</a></li>
- <li><a href="/zeit/next.js/tree/canary/examples/layout-component">Layout Component</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/head-elements">Head Elements</a></li>
+ <li><a href="/vercel/next.js/tree/canary/examples/layout-component">Layout Component</a></li>
</ul>
</details>
@@ -42,18 +42,10 @@ function IndexPage() {
<div>
<Head>
<title>My page title
-
+
-
+
Hello world!
@@ -63,9 +55,11 @@ function IndexPage() {
export default IndexPage
```
-In this case only the second `` is rendered.
+In this case only the second `` is rendered. `meta` tags with duplicate `name` attributes are automatically handled.
> The contents of `head` get cleared upon unmounting the component, so make sure each page completely defines what it needs in `head`, without making assumptions about what other pages added.
-`title`, `meta` or any other elements (e.g.`script`) need to be contained as **direct** children of the `Head` element,
-or wrapped into maximum one level of ``, otherwise the tags won't be correctly picked up on client-side navigations.
+`title`, `meta` or any other elements (e.g. `script`) need to be contained as **direct** children of the `Head` element,
+or wrapped into maximum one level of `` or arrays—otherwise the tags won't be correctly picked up on client-side navigations.
+
+> We recommend using [next/script](/docs/basic-features/script.md) in your component instead of manually creating a `
+
+// or
+
+
+```
+
+### Forwarding Attributes
+
+```js
+import Script from 'next/script'
+
+export default function Home() {
+ return (
+ <>
+
+
+ )
+}
+```
diff --git a/docs/basic-features/static-file-serving.md b/docs/basic-features/static-file-serving.md
index ffc0525641e82..c4234b7aa2f2e 100644
--- a/docs/basic-features/static-file-serving.md
+++ b/docs/basic-features/static-file-serving.md
@@ -6,20 +6,26 @@ description: Next.js allows you to serve static files, like images, in the publi
Next.js can serve static files, like images, under a folder called `public` in the root directory. Files inside `public` can then be referenced by your code starting from the base URL (`/`).
-For example, if you add an image to `public/my-image.png`, the following code will access the image:
+For example, if you add an image to `public/me.png`, the following code will access the image:
```jsx
-function MyImage() {
- return
+import Image from 'next/image'
+
+function Avatar() {
+ return
}
-export default MyImage
+export default Avatar
```
-This folder is also useful for `robots.txt`, Google Site Verification, and any other static files (including `.html`)!
+> Note: `next/image` requires Next.js 10 or later.
+
+This folder is also useful for `robots.txt`, `favicon.ico`, Google Site Verification, and any other static files (including `.html`)!
> **Note**: Don't name the `public` directory anything else. The name cannot be changed and is the only directory used to serve static assets.
> **Note**: Be sure to not have a static file with the same name as a file in the `pages/` directory, as this will result in an error.
>
-> Read more:
+> Read more:
+
+> **Note**: Only assets that are in the `public` directory at [build time](/docs/api-reference/cli.md#build) will be served by Next.js. Files added at runtime won't be available. We recommend using a third party service like [AWS S3](https://aws.amazon.com/s3/) for persistent file storage.
diff --git a/docs/basic-features/supported-browsers-features.md b/docs/basic-features/supported-browsers-features.md
new file mode 100644
index 0000000000000..9da03b356a6b1
--- /dev/null
+++ b/docs/basic-features/supported-browsers-features.md
@@ -0,0 +1,49 @@
+---
+description: Browser support and which JavaScript features are supported by Next.js.
+---
+
+# Supported Browsers and Features
+
+Next.js supports **IE11 and all modern browsers** (Edge, Firefox, Chrome, Safari, Opera, et al) with no required configuration.
+
+## Polyfills
+
+We transparently inject polyfills required for IE11 compatibility. In addition, we also inject widely used polyfills, including:
+
+- [**fetch()**](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) — Replacing: `whatwg-fetch` and `unfetch`.
+- [**URL**](https://developer.mozilla.org/en-US/docs/Web/API/URL) — Replacing: the [`url` package (Node.js API)](https://nodejs.org/api/url.html).
+- [**Object.assign()**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) — Replacing: `object-assign`, `object.assign`, and `core-js/object/assign`.
+
+If any of your dependencies includes these polyfills, they’ll be eliminated automatically from the production build to avoid duplication.
+
+In addition, to reduce bundle size, Next.js will only load these polyfills for browsers that require them. The majority of the web traffic globally will not download these polyfills.
+
+### Server-Side Polyfills
+
+In addition to `fetch()` on the client side, Next.js polyfills `fetch()` in the Node.js environment. You can use `fetch()` on your server code (such as `getStaticProps`) without using polyfills such as `isomorphic-unfetch` or `node-fetch`.
+
+### Custom Polyfills
+
+If your own code or any external npm dependencies require features not supported by your target browsers, you need to add polyfills yourself.
+
+In this case, you should add a top-level import for the **specific polyfill** you need in your [Custom ``](/docs/advanced-features/custom-app.md) or the individual component.
+
+## JavaScript Language Features
+
+Next.js allows you to use the latest JavaScript features out of the box. In addition to [ES6 features](https://github.com/lukehoban/es6features), Next.js also supports:
+
+- [Async/await](https://github.com/tc39/ecmascript-asyncawait) (ES2017)
+- [Object Rest/Spread Properties](https://github.com/tc39/proposal-object-rest-spread) (ES2018)
+- [Dynamic `import()`](https://github.com/tc39/proposal-dynamic-import) (ES2020)
+- [Optional Chaining](https://github.com/tc39/proposal-optional-chaining) (ES2020)
+- [Nullish Coalescing](https://github.com/tc39/proposal-nullish-coalescing) (ES2020)
+- [Class Fields](https://github.com/tc39/proposal-class-fields) and [Static Properties](https://github.com/tc39/proposal-static-class-features) (part of stage 3 proposal)
+- and more!
+
+### TypeScript Features
+
+Next.js has built-in TypeScript support. [Learn more here](/docs/basic-features/typescript.md).
+
+### Customizing Babel Config (Advanced)
+
+You can customize babel configuration. [Learn more here](/docs/advanced-features/customizing-babel-config.md).
diff --git a/docs/basic-features/typescript.md b/docs/basic-features/typescript.md
index c0ca541c079c2..8eeab64ceafe5 100644
--- a/docs/basic-features/typescript.md
+++ b/docs/basic-features/typescript.md
@@ -7,13 +7,27 @@ description: Next.js supports TypeScript by default and has built-in types for p
Examples
-Next.js provides an integrated [TypeScript](https://www.typescriptlang.org/) experience out of the box, similar to an IDE.
+Next.js provides an integrated [TypeScript](https://www.typescriptlang.org/)
+experience out of the box, similar to an IDE.
-To get started, create an empty `tsconfig.json` file in the root of your project:
+## `create-next-app` support
+
+You can create a TypeScript project with [`create-next-app`](https://nextjs.org/docs/api-reference/create-next-app) using the `--ts, --typescript` flag like so:
+
+```
+npx create-next-app --ts
+# or
+yarn create next-app --typescript
+```
+
+## Existing projects
+
+To get started in an existing project, create an empty `tsconfig.json` file in
+the root folder:
```bash
touch tsconfig.json
@@ -23,7 +37,7 @@ Next.js will automatically configure this file with default values. Providing yo
> Next.js uses Babel to handle TypeScript, which has some [caveats](https://babeljs.io/docs/en/babel-plugin-transform-typescript#caveats), and some [compiler options are handled differently](https://babeljs.io/docs/en/babel-plugin-transform-typescript#typescript-compiler-options).
-Then, run `next` (normally `npm run dev`) and Next.js will guide you through the installation of the required packages to finish the setup:
+Then, run `next` (normally `npm run dev` or `yarn dev`) and Next.js will guide you through the installation of the required packages to finish the setup:
```bash
npm run dev
@@ -39,11 +53,13 @@ npm run dev
You're now ready to start converting files from `.js` to `.tsx` and leveraging the benefits of TypeScript!.
-> A file named `next-env.d.ts` will be created in the root of your project. This file ensures Next.js types are picked up by the TypeScript compiler. **You cannot remove it**, however, you can edit it (but you don't need to).
+> A file named `next-env.d.ts` will be created in the root of your project. This file ensures Next.js types are picked up by the TypeScript compiler. **You cannot remove it or edit it** as it can change at any time.
-> Next.js `strict` mode is disabled by default. When you feel comfortable with TypeScript, it's recommended to turn it on in your `tsconfig.json`.
+> TypeScript `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.
+> Instead of editing `next-env.d.ts`, you can include additional types by adding a new file e.g. `additional.d.ts` and then referencing it in the [`include`](https://www.typescriptlang.org/tsconfig#include) array in your `tsconfig.json`.
+
+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).
@@ -54,7 +70,7 @@ For `getStaticProps`, `getStaticPaths`, and `getServerSideProps`, you can use th
```ts
import { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next'
-export const getStaticProps: GetStaticProps = async context => {
+export const getStaticProps: GetStaticProps = async (context) => {
// ...
}
@@ -62,7 +78,7 @@ export const getStaticPaths: GetStaticPaths = async () => {
// ...
}
-export const getServerSideProps: GetServerSideProps = async context => {
+export const getServerSideProps: GetServerSideProps = async (context) => {
// ...
}
```
@@ -74,7 +90,7 @@ export const getServerSideProps: GetServerSideProps = async context => {
The following is an example of how to use the built-in types for API routes:
```ts
-import { NextApiRequest, NextApiResponse } from 'next'
+import type { NextApiRequest, NextApiResponse } from 'next'
export default (req: NextApiRequest, res: NextApiResponse) => {
res.status(200).json({ name: 'John Doe' })
@@ -84,7 +100,7 @@ export default (req: NextApiRequest, res: NextApiResponse) => {
You can also type the response data:
```ts
-import { NextApiRequest, NextApiResponse } from 'next'
+import type { NextApiRequest, NextApiResponse } from 'next'
type Data = {
name: string
@@ -97,14 +113,56 @@ export default (req: NextApiRequest, res: NextApiResponse) => {
## Custom `App`
-If you have a [custom `App` ](/docs/advanced-features/custom-app), you can use the built-in type `AppProps` and change file name to `./pages/_app.tsx` like so:
+If you have a [custom `App`](/docs/advanced-features/custom-app.md), you can use the built-in type `AppProps` and change file name to `./pages/_app.tsx` like so:
```ts
-import { AppProps } from 'next/app'
+// import App from "next/app";
+import type { AppProps /*, AppContext */ } from 'next/app'
function MyApp({ Component, pageProps }: AppProps) {
return
}
+// Only uncomment this method if you have blocking data requirements for
+// every single page in your application. This disables the ability to
+// perform automatic static optimization, causing every page in your app to
+// be server-side rendered.
+//
+// MyApp.getInitialProps = async (appContext: AppContext) => {
+// // calls page's `getInitialProps` and fills `appProps.pageProps`
+// const appProps = await App.getInitialProps(appContext);
+
+// return { ...appProps }
+// }
+
export default MyApp
```
+
+## Path aliases and baseUrl
+
+Next.js automatically supports the `tsconfig.json` `"paths"` and `"baseUrl"` options.
+
+You can learn more about this feature on the [Module Path aliases documentation](/docs/advanced-features/module-path-aliases.md).
+
+## Type checking next.config.js
+
+The `next.config.js` file must be a JavaScript file as it does not get parsed by Babel or TypeScript, however you can add some type checking in your IDE using JSDoc as below:
+
+```js
+// @ts-check
+
+/**
+ * @type {import('next').NextConfig}
+ **/
+const nextConfig = {
+ /* config options here */
+}
+
+module.exports = nextConfig
+```
+
+## Incremental type checking
+
+Since `v10.2.1` Next.js supports [incremental type checking](https://www.typescriptlang.org/tsconfig#incremental) when enabled in your `tsconfig.json`, this can help speed up type checking in larger applications.
+
+It is highly recommended to be on at least `v4.3.2` of TypeScript to experience the [best performance](https://devblogs.microsoft.com/typescript/announcing-typescript-4-3/#lazier-incremental) when leveraging this feature.
diff --git a/docs/deployment.md b/docs/deployment.md
index 3ddbb1de16bbf..b4c30a3806163 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -1,54 +1,62 @@
---
-description: Deploy your Next.js app to production with ZEIT Now and other hosting options.
+description: Deploy your Next.js app to production with Vercel and other hosting options.
---
# Deployment
-## ZEIT Now (Recommended)
+## Vercel (Recommended)
-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.
+The easiest way to deploy Next.js to production is to use the **[Vercel platform](https://vercel.com)** from the creators of Next.js. [Vercel](https://vercel.com) is a cloud platform for static sites, hybrid apps, and Serverless Functions.
### Getting started
-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.
+If you haven’t already done so, push your Next.js app to a Git provider of your choice: [GitHub](https://github.com/), [GitLab](https://gitlab.com/), or [BitBucket](https://bitbucket.org/). Your repository can be private or public.
Then, follow these steps:
-1. [Sign up to ZEIT Now](https://zeit.co/signup) (no credit card is required).
-2. After signing up, you’ll arrive on the [“Import Project”](https://zeit.co/import) page. Under “From Git Repository”, 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 “Import 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!
+1. [Sign up to Vercel](https://vercel.com/signup) (no credit card is required).
+2. After signing up, you’ll arrive on the [“Import Project”](https://vercel.com/new) page. Under “From Git Repository”, choose the Git provider you use and set up an integration. (Instructions: [GitHub](https://vercel.com/docs/git/vercel-for-github) / [GitLab](https://vercel.com/docs/git/vercel-for-gitlab) / [BitBucket](https://vercel.com/docs/git/vercel-for-bitbucket)).
+3. Once that’s set up, click “Import 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 should work fine!
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.
-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).
+Congratulations! You’ve deployed your Next.js app! If you have questions, take a look at the [Vercel documentation](https://vercel.com/docs).
> 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).
### DPS: Develop, Preview, Ship
-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:
+Let’s talk about the workflow we recommend using. [Vercel](https://vercel.com) supports what we call the **DPS** workflow: **D**evelop, **P**review, and **S**hip:
-- **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.
+- **Develop:** Write code in Next.js. Keep the development server running and take advantage of [React Fast Refresh](https://nextjs.org/blog/next-9-4#fast-refresh).
+- **Preview:** Every time you push changes to a branch on GitHub / GitLab / BitBucket, Vercel 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 Vercel. [Learn more about it here](https://vercel.com/features/deployment-previews).
+- **Ship:** When you’re ready to ship, merge the pull request to your default branch (e.g. `main`). Vercel will automatically create a production deployment.
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.
### Optimized for Next.js
-[ZEIT Now](https://zeit.co) is made by the creators of Next.js and has first-class support for Next.js.
+[Vercel](https://vercel.com) is made by the creators of Next.js and has first-class support for Next.js.
For example, the [hybrid pages](/docs/basic-features/pages.md) approach is fully supported out of the box.
- 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 [Static Generation](/docs/basic-features/pages.md#static-generation) and assets (JS, CSS, images, fonts, etc) will automatically be served from [Vercel's Edge Network](https://vercel.com/docs/edge-network/overview), 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.
### Custom Domains, Environment Variables, Automatic HTTPS, and more
-- **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.
+- **Custom Domains:** Once deployed on [Vercel](https://vercel.com), you can assign a custom domain to your Next.js app. Take a look at [our documentation here](https://vercel.com/docs/custom-domains).
+- **Environment Variables:** You can also set environment variables on Vercel. Take a look at [our documentation here](https://vercel.com/docs/environment-variables). 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.
+- **More:** [Read our documentation](https://vercel.com/docs) to learn more about the Vercel platform.
+
+## Automatic Updates
+
+When you deploy your Next.js application, you want to see the latest version without needing to reload.
+
+Next.js will automatically load the latest version of your application in the background when routing. For client-side navigation, `next/link` will temporarily function as a normal `` tag.
+
+**Note:** If a new page (with an old version) has already been prefetched by `next/link`, Next.js will use the old version. Then, after either a full page refresh or multiple client-side page transitions, Next.js will show the latest version.
## Other hosting options
@@ -70,8 +78,67 @@ Make sure your `package.json` has the `"build"` and `"start"` scripts:
`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.
-### Static HTML Export
+### Docker Image
+
+
+ Examples
+
+
+
+Next.js can be deployed to any hosting provider that supports [Docker](https://www.docker.com/) containers. You can use this approach when deploying to container orchestrators such as [Kubernetes](https://kubernetes.io/) or [HashiCorp Nomad](https://www.nomadproject.io/), or when running inside a single node in any cloud provider.
+
+Here is a multi-stage `Dockerfile` using `node:alpine` that you can use:
+
+```Dockerfile
+# Install dependencies only when needed
+FROM node:alpine AS deps
+# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+
+# Rebuild the source code only when needed
+FROM node:alpine AS builder
+WORKDIR /app
+COPY . .
+COPY --from=deps /app/node_modules ./node_modules
+RUN yarn build && yarn install --production --ignore-scripts --prefer-offline
+
+# Production image, copy all the files and run next
+FROM node:alpine AS runner
+WORKDIR /app
-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.
+ENV NODE_ENV production
+
+RUN addgroup -g 1001 -S nodejs
+RUN adduser -S nextjs -u 1001
+
+# You only need to copy next.config.js if you are NOT using the default configuration
+# COPY --from=builder /app/next.config.js ./
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next ./.next
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+
+USER nextjs
+
+EXPOSE 3000
+
+# Next.js collects completely anonymous telemetry data about general usage.
+# Learn more here: https://nextjs.org/telemetry
+# Uncomment the following line in case you want to disable telemetry.
+# ENV NEXT_TELEMETRY_DISABLED 1
+
+CMD ["yarn", "start"]
+```
+
+Make sure to place this Dockerfile in the root folder of your project.
+
+You can build your container with `docker build . -t my-next-js-app` and run it with `docker run -p 3000:3000 my-next-js-app`.
+
+### Static HTML Export
-> 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.
+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).
diff --git a/docs/faq.md b/docs/faq.md
index cc7c3bc44f99b..8a1cec7254a91 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -4,16 +4,9 @@ description: Get to know more about Next.js with the frequently asked questions.
# Frequently Asked Questions
-
- What browsers are supported?
-
Next.js supports IE11 and all modern browsers out of the box using @babel/preset-env. In order to support IE11 Next.js adds a global Promise polyfill.
-
-
In cases where your own code or any external npm dependencies you are using require features not supported by your target browsers you will need to implement polyfills. If you need to implement polyfills, the polyfills example demonstrates the recommended approach.
-
-
Is this production ready?
-
Next.js has been powering https://zeit.co since its inception.
We’re ecstatic about both the developer experience and end-user performance, so we decided to share it with the community.
@@ -46,17 +39,17 @@ description: Get to know more about Next.js with the frequently asked questions.
How do I fetch data?
-
It's up to you. You can use the fetch API or SWR inside your React components for remote data fetching; or use our data fetching methods for initial data population.
+
It's up to you. You can use the fetch API or SWR inside your React components for remote data fetching; or use our data fetching methods for initial data population.
@@ -66,7 +59,7 @@ description: Get to know more about Next.js with the frequently asked questions.
Can I use Next with my favorite JavaScript library or toolkit?
-
Since our first release we've had many example contributions. You can check them out in the examples directory.
+
Since our first release we've had many example contributions. You can check them out in the examples directory.
@@ -79,3 +72,8 @@ description: Get to know more about Next.js with the frequently asked questions.
As we were researching options for server-rendering React that didn’t involve a large number of steps, we came across react-page (now deprecated), a similar approach to Next.js by the creator of React Jordan Walke.
+
+
+ Can I make a Next.js Progressive Web App (PWA)?
+
Yes! Check out our PWA Example to see how it works.
+
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 069f67280abb3..ebe35fa1159a5 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -6,15 +6,15 @@ description: Get started with Next.js in the official documentation, and learn m
Welcome to the Next.js documentation!
-If you're new to Next.js we recommend that you start with the [learn course](https://nextjs.org/learn/basics/getting-started).
+If you're new to Next.js we recommend that you start with the [learn course](https://nextjs.org/learn/basics/create-nextjs-app).
The interactive course with quizzes will guide you through everything you need to know to use Next.js.
-If you have questions about anything related to Next.js, you're always welcome to ask our community on [GitHub Discussions](https://github.com/zeit/next.js/discussions).
+If you have questions about anything related to Next.js, you're always welcome to ask our community on [GitHub Discussions](https://github.com/vercel/next.js/discussions).
#### System Requirements
-- [Node.js 10.13](https://nodejs.org/) or later
+- [Node.js 12.0](https://nodejs.org/) or later
- MacOS, Windows (including WSL), and Linux are supported
## Setup
@@ -22,38 +22,52 @@ If you have questions about anything related to Next.js, you're always welcome t
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
+npx create-next-app
# or
yarn create next-app
```
+If you want to start with a TypeScript project you can use the `--typescript` flag:
+
+```bash
+npx create-next-app --typescript
+# or
+yarn create next-app --typescript
+```
+
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.
+For more information on how to use `create-next-app`, you can review the [`create-next-app` documentation](/docs/api-reference/create-next-app.md)
+
## Manual Setup
Install `next`, `react` and `react-dom` in your project:
```bash
npm install next react react-dom
+# or
+yarn add next react react-dom
```
Open `package.json` and add the following `scripts`:
```json
"scripts": {
- "dev": "next",
+ "dev": "next dev",
"build": "next build",
- "start": "next start"
+ "start": "next start",
+ "lint": "next lint"
}
```
These scripts refer to the different stages of developing an application:
-- `dev` - Runs `next` which starts Next.js in development mode
-- `build` - Runs `next build` which builds the application for production usage
-- `start` - Runs `next start` which starts a Next.js production server
+- `dev` - Runs [`next dev`](/docs/api-reference/cli.md#development) which starts Next.js in development mode
+- `build` - Runs [`next build`](/docs/api-reference/cli.md#build) which builds the application for production usage
+- `start` - Runs [`next start`](/docs/api-reference/cli.md#production) which starts a Next.js production server
+- `lint` - Runs [`next lint`](/docs/api-reference/cli.md#lint) which sets up Next.js' built-in ESLint configuration
-Next.js is built around the concept of pages. A page is a [React Component](https://reactjs.org/docs/components-and-props.html) exported from a `.js`, `.jsx`, `.ts`, or `.tsx` file in the `pages` directory.
+Next.js is built around the concept of [pages](/docs/basic-features/pages.md). A page is a [React Component](https://reactjs.org/docs/components-and-props.html) exported from a `.js`, `.jsx`, `.ts`, or `.tsx` file in the `pages` directory.
Pages are associated with a route based on their file name. For example `pages/about.js` is mapped to `/about`. You can even add dynamic route parameters with the filename.
@@ -69,17 +83,19 @@ function HomePage() {
export default HomePage
```
-To start developing your application run `npm run dev`. This starts the development server on `http://localhost:3000`.
+To start developing your application run `npm run dev` or `yarn dev`. This starts the development server on `http://localhost:3000`.
Visit `http://localhost:3000` to view your application.
So far, we get:
- Automatic compilation and bundling (with webpack and babel)
-- Hot code reloading
-- Static generation and server-side rendering of [`./pages/`](/docs/basic-features/pages.md)
+- [React Fast Refresh](https://nextjs.org/blog/next-9-4#fast-refresh)
+- [Static generation and server-side rendering](/docs/basic-features/data-fetching.md) of [`./pages/`](/docs/basic-features/pages.md)
- [Static file serving](/docs/basic-features/static-file-serving.md). `./public/` is mapped to `/`
+In addition, any Next.js application is ready for production from the start, read more in our [Deployment documentation](/docs/deployment.md).
+
## Related
For more information on what to do next, we recommend the following sections:
@@ -97,3 +113,10 @@ For more information on what to do next, we recommend the following sections:
Use the built-in CSS support to add custom styles to your app.
+
+
diff --git a/docs/going-to-production.md b/docs/going-to-production.md
new file mode 100644
index 0000000000000..55d94ef2b5728
--- /dev/null
+++ b/docs/going-to-production.md
@@ -0,0 +1,129 @@
+---
+description: Before taking your Next.js application to production, here are some recommendations to ensure the best user experience.
+---
+
+# Going to Production
+
+Before taking your Next.js application to production, here are some recommendations to ensure the best user experience.
+
+## In General
+
+- Use [caching](#caching) wherever possible.
+- Ensure your database and backend are deployed in the same region.
+- Aim to ship the least amount of JavaScript possible.
+- Defer loading heavy JavaScript bundles until needed.
+- Ensure [logging](#logging) is set up.
+- Ensure [error handling](#error-handling) is set up.
+- Configure the [404](/docs/advanced-features/custom-error-page.md#404-page) (Not Found) and [500](/docs/advanced-features/custom-error-page.md#500-page) (Error) pages.
+- Ensure you are [measuring performance](/docs/advanced-features/measuring-performance.md).
+- Run [Lighthouse](https://developers.google.com/web/tools/lighthouse) to check for performance, best practices, accessibility, and SEO. For best results, use a production build of Next.js and use incognito in your browser so results aren't affected by extensions.
+- Review [Supported Browsers and Features](/docs/basic-features/supported-browsers-features.md).
+- Improve performance using:
+ - [`next/image` and Automatic Image Optimization](/docs/basic-features/image-optimization.md)
+ - [Automatic Font Optimization](/docs/basic-features/font-optimization.md)
+ - [Script Optimization](/docs/basic-features/script.md)
+
+## Caching
+
+
+ Examples
+
+
+
+Caching improves response times and reduces the number of requests to external services. Next.js automatically adds caching headers to immutable assets served from `/_next/static` including JavaScript, CSS, static images, and other media.
+
+```
+Cache-Control: public, max-age=31536000, immutable
+```
+
+`Cache-Control` headers set in `next.config.js` will be overwritten in production to ensure that static assets can be cached effectively. If you need to revalidate the cache of a page that has been [statically generated](/docs/basic-features/pages.md#static-generation-recommended), you can do so by setting `revalidate` in the page's [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) function. If you're using `next/image`, there are also [specific caching rules](/docs/basic-features/image-optimization.md#caching) for the default Image Optimization loader.
+
+**Note:** When running your application locally with `next dev`, your headers are overwritten to prevent caching locally.
+
+```
+Cache-Control: no-cache, no-store, max-age=0, must-revalidate
+```
+
+You can also use caching headers inside `getServerSideProps` and API Routes for dynamic responses. For example, using [`stale-while-revalidate`](https://web.dev/stale-while-revalidate/).
+
+```jsx
+// This value is considered fresh for ten seconds (s-maxage=10).
+// If a request is repeated within the next 10 seconds, the previously
+// cached value will still be fresh. If the request is repeated before 59 seconds,
+// the cached value will be stale but still render (stale-while-revalidate=59).
+//
+// In the background, a revalidation request will be made to populate the cache
+// with a fresh value. If you refresh the page, you will see the new value.
+export async function getServerSideProps({ req, res }) {
+ res.setHeader(
+ 'Cache-Control',
+ 'public, s-maxage=10, stale-while-revalidate=59'
+ )
+
+ return {
+ props: {},
+ }
+}
+```
+
+> **Note:** Your deployment provider must support edge caching for dynamic responses. If you are self-hosting, you will need to add this logic to the edge yourself using a key/value store. If you are using Vercel, [edge caching works without configuration](https://vercel.com/docs/edge-network/caching).
+
+## Reducing JavaScript Size
+
+
+ Examples
+
+
+
+To reduce the amount of JavaScript sent to the browser, you can use the following tools to understand what is included inside each JavaScript bundle:
+
+- [Import Cost](https://marketplace.visualstudio.com/items?itemName=wix.vscode-import-cost) – Display the size of the imported package inside VSCode.
+- [Package Phobia](https://packagephobia.com/) – Find the cost of adding a new dev dependency to your project.
+- [Bundle Phobia](https://bundlephobia.com/) - Analyze how much a dependency can increase bundle sizes.
+- [Webpack Bundle Analyzer](https://github.com/vercel/next.js/tree/canary/packages/next-bundle-analyzer) – Visualize size of webpack output files with an interactive, zoomable treemap.
+
+Each file inside your `pages/` directory will automatically be code split into its own JavaScript bundle during `next build`. You can also use [Dynamic Imports](/docs/advanced-features/dynamic-import.md) to lazy-load components and libraries. For example, you might want to defer loading your modal code until a user clicks the open button.
+
+## Logging
+
+
+ Examples
+
+
+
+Since Next.js runs on both the client and server, there are multiple forms of logging supported:
+
+- `console.log` in the browser
+- `stdout` on the server
+
+If you want a structured logging package, we recommend [Pino](https://www.npmjs.com/package/pino). If you're using Vercel, there are [pre-built logging integrations](https://vercel.com/integrations#logging) compatible with Next.js.
+
+## Error Handling
+
+
+ Examples
+
+
+
+When an unhandled exception occurs, you can control the experience for your users with the [500 page](/docs/advanced-features/custom-error-page.md#500-page). We recommend customizing this to your brand instead of the default Next.js theme.
+
+You can also log and track exceptions with a tool like Sentry. [This example](https://github.com/vercel/next.js/tree/canary/examples/with-sentry) shows how to catch & report errors on both the client and server-side, using the Sentry SDK for Next.js. There's also a [Sentry integration for Vercel](https://vercel.com/integrations/sentry).
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+
+
+
+
+ )
+}
+```
+
+With Next.js, you can express the same application structure in the file system. When a file is added to the [`pages`](/docs/basic-features/pages.md) directory it's automatically available as a route.
+
+- `pages/about.js` → `/about`
+- `pages/blog.js` → `/blog`
+- `pages/index.js` → `/`
+
+## Nested Routes
+
+In the example below, routes like `/blog/my-post` would render the `Post` component. If a slug was not provided, it would render the list of all blog posts.
+
+```jsx
+import {
+ BrowserRouter as Router,
+ Switch,
+ Route,
+ useRouteMatch,
+ useParams,
+} from 'react-router-dom'
+
+export default function Blog() {
+ // Nested route under /blog
+ const match = useRouteMatch()
+
+ return (
+
+
+
+
+
+
+
+}
+```
+
+Rather than using the `:slug` syntax inside your `Route` component, Next.js uses the `[slug]` syntax in the file name for [Dynamic Routes](/docs/routing/dynamic-routes.md). We can transform this to Next.js by creating two new files, `pages/blog/index.js` (showing all pages) and `pages/blog/[slug].js` (showing an individual post).
+
+```jsx
+// pages/blog/index.js
+
+export default function Blog() {
+ return
+}
+```
+
+## Server Rendering
+
+Next.js has built-in support for [Server-side Rendering](/docs/basic-features/pages#server-side-rendering.md). This means you can remove any instances of `StaticRouter` in your code.
+
+## Code Splitting
+
+Next.js has built-in support for [Code Splitting](https://reactrouter.com/web/guides/code-splitting). This means you can remove any instances of:
+
+- `@loadable/server`, `@loadable/babel-plugin`, and `@loadable/webpack-plugin`
+- Modifications to your `.babelrc` for `@loadable/babel-plugin`
+
+Each file inside your `pages/` directory will be code split into its own JavaScript bundle during the build process. Next.js [also supports](/docs/basic-features/supported-browsers-features.md#javascript-language-features) ES2020 dynamic `import()` for JavaScript. With it you can import JavaScript modules dynamically and work with them. They also work with SSR.
+
+For more information, read about [Dynamic Imports](https://nextjs.org/docs/advanced-features/dynamic-import).
+
+## Scroll Restoration
+
+Next.js has built-in support for [Scroll Restoration](https://reactrouter.com/web/guides/scroll-restoration). This means you can remove any custom `ScrollToTop` components you have defined.
+
+The default behavior of `next/link` and `next/router` is to scroll to the top of the page. You can also [disable this](https://nextjs.org/docs/api-reference/next/link#disable-scrolling-to-the-top-of-the-page) if you prefer.
+
+## Learn More
+
+For more information on what to do next, we recommend the following sections:
+
+
+
+
+Next.js has been designed for gradual adoption. With Next.js, you can continue using your existing code and add as much (or as little) React as you need. By starting small and incrementally adding more pages, you can prevent derailing feature work by avoiding a complete rewrite.
+
+## Strategies
+
+### Subpath
+
+The first strategy is to configure your server or proxy such that, everything under a specific subpath points to a Next.js app. For example, your existing website might be at `example.com`, and you might configure your proxy such that `example.com/store` serves a Next.js e-commerce store.
+
+Using [`basePath`](/docs/api-reference/next.config.js/basepath.md), you can configure your Next.js application's assets and links to automatically work with your new subpath `/store`. Since each page in Next.js is its own [standalone route](/docs/routing/introduction.md), pages like `pages/products.js` will route to `example.com/store/products` in your application.
+
+```jsx
+// next.config.js
+
+module.exports = {
+ basePath: '/store',
+}
+```
+
+To learn more about `basePath`, take a look at our [documentation](/docs/api-reference/next.config.js/basepath.md).
+
+> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
+
+### Rewrites
+
+The second strategy is to create a new Next.js app that points to the root URL of your domain. Then, you can use [`rewrites`](/docs/api-reference/next.config.js/rewrites.md) inside `next.config.js` to have some subpaths to be proxied to your existing app.
+
+For example, let's say you created a Next.js app to be served from `example.com` with the following `next.config.js`. Now, requests for the pages you’ve added to this Next.js app (e.g. `/about` if you’ve added `pages/about.js`) will be handled by Next.js, and requests for any other route (e.g. `/dashboard`) will be proxied to `proxy.example.com`.
+
+```jsx
+// next.config.js
+
+module.exports = {
+ async rewrites() {
+ return {
+ // After checking all Next.js pages (including dynamic routes)
+ // and static files we proxy any other requests
+ fallback: [
+ {
+ source: '/:path*',
+ destination: `https://proxy.example.com/:path*`,
+ },
+ ],
+ }
+
+ // For versions of Next.js < v10.1 you can use a no-op rewrite instead
+ return [
+ // we need to define a no-op rewrite to trigger checking
+ // all pages/static files before we attempt proxying
+ {
+ source: '/:path*',
+ destination: '/:path*',
+ },
+ {
+ source: '/:path*',
+ destination: `https://proxy.example.com/:path*`,
+ },
+ ]
+ },
+}
+```
+
+To learn more about rewrites, take a look at our [documentation](/docs/api-reference/next.config.js/rewrites.md).
+
+> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
+
+### Micro-Frontends with Monorepos and Subdomains
+
+Next.js and [Vercel](https://vercel.com) make it straightforward to adopt [micro-frontends](https://martinfowler.com/articles/micro-frontends.html) and deploy as a [Monorepo](https://vercel.com/blog/monorepos). This allows you to use [subdomains](https://en.wikipedia.org/wiki/Subdomain) to adopt new applications incrementally. Some benefits of micro-frontends:
+
+- Smaller, more cohesive and maintainable codebases.
+- More scalable organizations with decoupled, autonomous teams.
+- The ability to upgrade, update, or even rewrite parts of the frontend in a more incremental fashion.
+
+Once your monorepo is set up, push changes to your Git repository as usual and you'll see the commits deployed to the Vercel projects you've connected.
+
+## Conclusion
+
+To learn more, read about [subpaths](/docs/api-reference/next.config.js/basepath.md) and [rewrites](/docs/api-reference/next.config.js/rewrites.md) or [deploy an example with micro-frontends](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/with-zones&project-name=with-zones&repository-name=with-zones).
diff --git a/docs/routing/dynamic-routes.md b/docs/routing/dynamic-routes.md
index 1d64d9d67023f..9f0b7f66517f4 100644
--- a/docs/routing/dynamic-routes.md
+++ b/docs/routing/dynamic-routes.md
@@ -7,7 +7,7 @@ description: Dynamic Routes are pages that allow you to add custom params to you
Examples
@@ -54,14 +54,44 @@ 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).
+Client-side navigations to dynamic routes are handled with [`next/link`](/docs/api-reference/next/link.md). If we wanted to have links to the routes used above it will look like this:
+
+```jsx
+import Link from 'next/link'
+
+function Home() {
+ return (
+
+ )
+}
+
+export default Home
+```
+
+Read our docs for [Linking between pages](/docs/routing/introduction.md#linking-between-pages) to learn more.
### Catch all routes
Examples
@@ -83,7 +113,21 @@ And in the case of `/post/a/b`, and any other matching path, new parameters will
{ "slug": ["a", "b"] }
```
-> A good example of catch all routes is the Next.js docs, a single page called [pages/docs/[...slug].js](https://github.com/zeit/next-site/blob/master/pages/docs/%5B...slug%5D.js) takes care of all the docs you're currently looking at.
+### Optional catch all routes
+
+Catch all routes can be made optional by including the parameter in double brackets (`[[...slug]]`).
+
+For example, `pages/post/[[...slug]].js` will match `/post`, `/post/a`, `/post/a/b`, and so on.
+
+The main difference between catch all and optional catch all routes is that with optional, the route without the parameter is also matched (`/post` in the example above).
+
+The `query` objects are as follows:
+
+```json
+{ } // GET `/post` (empty object)
+{ "slug": ["a"] } // `GET /post/a` (single-element array)
+{ "slug": ["a", "b"] } // `GET /post/a/b` (multi-element array)
+```
## Caveats
@@ -94,3 +138,21 @@ And in the case of `/post/a/b`, and any other matching path, new parameters will
- 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.
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+
diff --git a/docs/routing/imperatively.md b/docs/routing/imperatively.md
index f555132a0c5bd..7dbbf7a16a42d 100644
--- a/docs/routing/imperatively.md
+++ b/docs/routing/imperatively.md
@@ -1,5 +1,5 @@
---
-description: Client-side navigations are also possible using the Router API instead of the Link component. Learn more here.
+description: Client-side navigations are also possible using the Next.js Router instead of the Link component. Learn more here.
---
# Imperatively
@@ -7,22 +7,22 @@ description: Client-side navigations are also possible using the Router API inst
Examples
-[`next/link`](/docs/api-reference/next/link.md) should be able to cover most of your routing needs, but you can also do client-side navigations without it, take a look at the [Router API documentation](/docs/api-reference/next/router.md#router-api).
+[`next/link`](/docs/api-reference/next/link.md) should be able to cover most of your routing needs, but you can also do client-side navigations without it, take a look at the [documentation for `next/router`](/docs/api-reference/next/router.md).
-The following example shows the basic usage of the Router API:
+The following example shows how to do basic page navigations with [`useRouter`](/docs/api-reference/next/router.md#useRouter):
```jsx
-import Router from 'next/router'
+import { useRouter } from 'next/router'
function ReadMore() {
+ const router = useRouter()
+
return (
-
- Click Router.push('/about')}>here to read more
-
+ router.push('/about')}>Click here to read more
)
}
diff --git a/docs/routing/introduction.md b/docs/routing/introduction.md
index d5e19315067df..575c65db1792f 100644
--- a/docs/routing/introduction.md
+++ b/docs/routing/introduction.md
@@ -32,11 +32,13 @@ To match a dynamic segment you can use the bracket syntax. This allows you to ma
- `pages/[username]/settings.js` → `/:username/settings` (`/foo/settings`)
- `pages/post/[...all].js` → `/post/*` (`/post/2020/id/title`)
+> Check out the [Dynamic Routes documentation](/docs/routing/dynamic-routes.md) to learn more about how they work.
+
## Linking between pages
-The Next.js router allows you to do client-side route transitions between pages, similarly to a single-page application.
+The Next.js router allows you to do client-side route transitions between pages, similar to a single-page application.
-A special React component called `Link` is provided to do this client-side route transition.
+A React component called `Link` is provided to do this client-side route transition.
```jsx
import Link from 'next/link'
@@ -54,6 +56,11 @@ function Home() {
About Us
+
)
}
@@ -61,38 +68,56 @@ function Home() {
export default Home
```
-When linking to a route with [dynamic path segments](/docs/routing/dynamic-routes.md) you have to provide `href` and `as` to make sure the router knows which JavaScript file to load.
+In the example above we have multiple links, each one maps a path (`href`) to a known page:
+
+- `/` → `pages/index.js`
+- `/about` → `pages/about.js`
+- `/blog/hello-world` → `pages/blog/[slug].js`
+
+Any `` in the viewport (initially or through scroll) will be prefetched by default (including the corresponding data) for pages using [Static Generation](/docs/basic-features/data-fetching.md#getstaticprops-static-generation). The corresponding data for [server-rendered](https://nextjs.org/docs/basic-features/data-fetching#getserversideprops-server-side-rendering) routes is _not_ prefetched.
-- `href` - The name of the page in the `pages` directory. For example `/blog/[slug]`.
-- `as` - The url that will be shown in the browser. For example `/blog/hello-world`.
+### Linking to dynamic paths
+
+You can also use interpolation to create the path, which comes in handy for [dynamic route segments](#dynamic-route-segments). For example, to show a list of posts which have been passed to the component as a prop:
```jsx
import Link from 'next/link'
-function Home() {
+function Posts({ posts }) {
return (
)
}
-export default Home
+export default Posts
```
-The `as` prop can also be generated dynamically. For example, to show a list of posts which have been passed to the page as a prop:
+> [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) is used in the example to keep the path utf-8 compatible.
+
+Alternatively, using a URL Object:
```jsx
-function Home({ posts }) {
+import Link from 'next/link'
+
+function Posts({ posts }) {
return (
)
}
+
+export default Posts
```
+Now, instead of using interpolation to create the path, we use a URL object in `href` where:
+
+- `pathname` is the name of the page in the `pages` directory. `/blog/[slug]` in this case.
+- `query` is an object with the dynamic segment. `slug` in this case.
+
## Injecting the router
Examples
diff --git a/docs/routing/shallow-routing.md b/docs/routing/shallow-routing.md
index c9d5b5e39bc61..caa9cf35138e1 100644
--- a/docs/routing/shallow-routing.md
+++ b/docs/routing/shallow-routing.md
@@ -7,7 +7,7 @@ description: You can use shallow routing to change the URL without triggering a
Examples
@@ -27,7 +27,7 @@ function Page() {
useEffect(() => {
// Always do navigations after the first render
- router.push('/?counter=10', null, { shallow: true })
+ router.push('/?counter=10', undefined, { shallow: true })
}, [])
useEffect(() => {
@@ -38,14 +38,6 @@ function Page() {
export default Page
```
-If you don't need to add the router object to the page, you can also use the [Router API](/docs/api-reference/next/router.md#router-api) directly, like so:
-
-```jsx
-import Router from 'next/router'
-// Inside your page
-Router.push('/?counter=10', null, { shallow: true })
-```
-
The URL will get updated to `/?counter=10`. and the page won't get replaced, only the state of the route is changed.
You can also watch for URL changes via [`componentDidUpdate`](https://reactjs.org/docs/react-component.html#componentdidupdate) as shown below:
@@ -65,7 +57,7 @@ componentDidUpdate(prevProps) {
Shallow routing **only** works for same page URL changes. For example, let's assume we have another page called `pages/about.js`, and you run this:
```jsx
-Router.push('/?counter=10', '/about?counter=10', { shallow: true })
+router.push('/?counter=10', '/about?counter=10', { shallow: true })
```
Since that's a new page, it'll unload the current page, load the new one and wait for data fetching even though we asked to do shallow routing.
diff --git a/docs/upgrading.md b/docs/upgrading.md
index d5be42132d862..08a607ae83f4a 100644
--- a/docs/upgrading.md
+++ b/docs/upgrading.md
@@ -4,21 +4,180 @@ description: Learn how to upgrade Next.js.
# Upgrade Guide
-## Upgrading from version 8 to 9.0.x
+## Upgrading from version 10 to 11
+
+### Upgrade React version to latest
+
+Most applications already use the latest version of React, with Next.js 11 the minimum React version has been updated to 17.0.2.
+
+To upgrade you can run the following command:
+
+```
+npm install react@latest react-dom@latest
+```
+
+Or using `yarn`:
+
+```
+yarn add react@latest react-dom@latest
+```
+
+### Upgrade Next.js version to latest
+
+To upgrade you can run the following command in the terminal:
+
+```
+npm install next@latest
+```
+
+or
+
+```
+yarn add next@latest
+```
+
+### Webpack 5
+
+Webpack 5 is now the default for all Next.js applications. If you did not have custom webpack configuration your application is already using webpack 5. If you do have custom webpack configuration you can refer to the [Next.js webpack 5 documentation](https://nextjs.org/docs/messages/webpack5) for upgrading guidance.
+
+### Cleaning the `distDir` is now a default
+
+The build output directory (defaults to `.next`) is now cleared by default except for the Next.js caches. You can refer to [the cleaning `distDir` RFC](https://github.com/vercel/next.js/discussions/6009) for more information.
+
+If your application was relying on this behavior previously you can disable the new default behavior by adding the `cleanDistDir: false` flag in `next.config.js`.
+
+### `PORT` is now supported for `next dev` and `next start`
+
+Next.js 11 supports the `PORT` environment variable to set the port the application has to run on. Using `-p`/`--port` is still recommended but if you were prohibited from using `-p` in any way you can now use `PORT` as an alternative:
+
+Example:
+
+```
+PORT=4000 next start
+```
+
+### `next.config.js` customization to import images
+
+Next.js 11 supports static image imports with `next/image`. This new feature relies on being able to process image imports. If you previously added the `next-images` or `next-optimized-images` packages you can either move to the new built-in support using `next/image` or disable the feature:
+
+```js
+module.exports = {
+ images: {
+ disableStaticImages: true,
+ },
+}
+```
+
+### Remove `super.componentDidCatch()` from `pages/_app.js`
+
+The `next/app` component's `componentDidCatch` has been deprecated since Next.js 9 as it's no longer needed and has since been a no-op, in Next.js 11 it has been removed.
+
+If your `pages/_app.js` has a custom `componentDidCatch` method you can remove `super.componentDidCatch` as it is no longer needed.
+
+### Remove `Container` from `pages/_app.js`
+
+This export has been deprecated since Next.js 9 as it's no longer needed and has since been a no-op with a warning during development. In Next.js 11 it has been removed.
+
+If your `pages/_app.js` imports `Container` from `next/app` you can remove `Container` as it has been removed. Learn more in [the documentation](https://nextjs.org/docs/messages/app-container-deprecated).
+
+### Remove `props.url` usage from page components
+
+This property has been deprecated since Next.js 4 and has since shown a warning during development. With the introduction of `getStaticProps` / `getServerSideProps` these methods already disallowed usage of `props.url`. In Next.js 11 it has been removed completely.
+
+You can learn more in [the documentation](https://nextjs.org/docs/messages/url-deprecated).
+
+### Remove `unsized` property on `next/image`
+
+The `unsized` property on `next/image` was deprecated in Next.js 10.0.1. You can use `layout="fill"` instead. In Next.js 11 `unsized` was removed.
+
+### Remove `modules` property on `next/dynamic`
+
+The `modules` and `render` option for `next/dynamic` have been deprecated since Next.js 9.5 showing a warning that it has been deprecated. This was done in order to make `next/dynamic` close to `React.lazy` in API surface. In Next.js 11 the `modules` and `render` options have been removed.
+
+This option hasn't been mentioned in the documentation since Next.js 8 so it's less likely that your application is using it.
+
+If you application does use `modules` and `render` you can refer to [the documentation](https://nextjs.org/docs/messages/next-dynamic-modules).
+
+### Remove `Head.rewind`
+
+`Head.rewind` has been a no-op since Next.js 9.5, in Next.js 11 it was removed. You can safely remove your usage of `Head.rewind`.
+
+### Moment.js locales excluded by default
+
+Moment.js includes translations for a lot of locales by default. Next.js now automatically excludes these locales by default to optimize bundle size for applications using Moment.js.
+
+To load a specific locale use this snippet:
+
+```js
+import moment from 'moment'
+import 'moment/locale/ja'
+
+moment.locale('ja')
+```
+
+You can opt-out of this new default by adding `excludeDefaultMomentLocales: false` to `next.config.js` if you do not want the new behavior, do note it's highly recommended to not disable this new optimization as it significantly reduces the size of Moment.js.
+
+### Update usage of `router.events`
+
+In case you're accessing `router.events` during rendering, in Next.js 11 `router.events` is no longer provided during pre-rendering. Ensure you're accessing `router.events` in `useEffect`:
+
+```js
+useEffect(() => {
+ const handleRouteChange = (url, { shallow }) => {
+ console.log(
+ `App is changing to ${url} ${
+ shallow ? 'with' : 'without'
+ } shallow routing`
+ )
+ }
+
+ router.events.on('routeChangeStart', handleRouteChange)
+
+ // If the component is unmounted, unsubscribe
+ // from the event with the `off` method:
+ return () => {
+ router.events.off('routeChangeStart', handleRouteChange)
+ }
+}, [router])
+```
+
+If your application uses `router.router.events` which was an internal property that was not public please make sure to use `router.events` as well.
+
+## React 16 to 17
+
+React 17 introduced a new [JSX Transform](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) that brings a long-time Next.js feature to the wider React ecosystem: Not having to `import React from 'react'` when using JSX. When using React 17 Next.js will automatically use the new transform. This transform does not make the `React` variable global, which was an unintended side-effect of the previous Next.js implementation. A [codemod is available](/docs/advanced-features/codemods.md#add-missing-react-import) to automatically fix cases where you accidentally used `React` without importing it.
+
+## Upgrading from version 9 to 10
+
+There were no breaking changes between version 9 and 10.
+
+To upgrade run the following command:
+
+```
+npm install next@10
+```
+
+Or using `yarn`:
+
+```
+yarn add next@10
+```
+
+## Upgrading from version 8 to 9
### Preamble
-#### Production Deployment on ZEIT Now v2
+#### Production Deployment on Vercel
-If you previously configured `routes` in your `now.json` file for dynamic routes, these rules can be removed when leveraging Next.js 9's new [Dynamic Routing feature](https://nextjs.org/docs/routing/dynamic-routes).
+If you previously configured `routes` in your `vercel.json` file for dynamic routes, these rules can be removed when leveraging Next.js 9's new [Dynamic Routing feature](/docs/routing/dynamic-routes.md).
-Next.js 9's dynamic routes are **automatically configured on [Now](https://zeit.co/now)** and do not require any `now.json` customization.
+Next.js 9's dynamic routes are **automatically configured on [Vercel](https://vercel.com/)** and do not require any `vercel.json` customization.
-You can read more about [Dynamic Routing here](https://nextjs.org/docs/routing/dynamic-routes).
+You can read more about [Dynamic Routing here](/docs/routing/dynamic-routes.md).
#### Check your Custom (`pages/_app.js`)
-If you previously copied the [Custom ``](https://nextjs.org/docs#custom-app) example, you may be able to remove your `getInitialProps`.
+If you previously copied the [Custom ``](/docs/advanced-features/custom-app.md) example, you may be able to remove your `getInitialProps`.
Removing `getInitialProps` from `pages/_app.js` (when possible) is important to leverage new Next.js features!
@@ -75,7 +234,7 @@ import { AppContext, AppInitialProps } from 'next/app'
import { DocumentContext, DocumentInitialProps } from 'next/document'
```
-#### The `config` key is now a special export on a page
+#### The `config` key is now an export on a page
You may no longer export a custom variable named `config` from a page (i.e. `export { config }` / `export const config ...`).
This exported variable is now used to specify page-level Next.js configuration like Opt-in AMP and API Route features.
@@ -104,7 +263,7 @@ Next.js now has the concept of page-level configuration, so the `withAmp` higher
This change can be **automatically migrated by running the following commands in the root of your Next.js project:**
```bash
-curl -L https://github.com/zeit/next-codemod/archive/master.tar.gz | tar -xz --strip=2 next-codemod-master/transforms/withamp-to-config.js npx jscodeshift -t ./withamp-to-config.js pages/**/*.js
+curl -L https://github.com/vercel/next-codemod/archive/master.tar.gz | tar -xz --strip=2 next-codemod-master/transforms/withamp-to-config.js npx jscodeshift -t ./withamp-to-config.js pages/**/*.js
```
To perform this migration by hand, or view what the codemod will produce, see below:
@@ -146,7 +305,7 @@ You can revert to the previous behavior by creating a `next.config.js` with the
```js
// next.config.js
module.exports = {
- exportTrailingSlash: true,
+ trailingSlash: true,
}
```
@@ -171,8 +330,8 @@ import dynamic from 'next/dynamic'
const HelloBundle = dynamic({
modules: () => {
const components = {
- Hello1: () => import('../components/hello1').then(m => m.default),
- Hello2: () => import('../components/hello2').then(m => m.default),
+ Hello1: () => import('../components/hello1').then((m) => m.default),
+ Hello2: () => import('../components/hello2').then((m) => m.default),
}
return components
diff --git a/errors/api-routes-body-size-limit.md b/errors/api-routes-body-size-limit.md
new file mode 100644
index 0000000000000..5697768c4a089
--- /dev/null
+++ b/errors/api-routes-body-size-limit.md
@@ -0,0 +1,13 @@
+# API Routes Body Size Limited to 4MB
+
+#### Why This Error Occurred
+
+API Routes are meant to respond quickly and are not intended to support responding with large amounts of data. The maximum size of responses is 4 MB.
+
+#### Possible Ways to Fix It
+
+Limit your API Route responses to less than 4 MB. If you need to support sending large files to the client, you should consider using a dedicated media host for those assets. See link below for suggestions.
+
+### Useful Links
+
+[Tips to avoid the 5 MB limit](https://vercel.com/support/articles/how-to-bypass-vercel-5mb-body-size-limit-serverless-functions)
diff --git a/errors/api-routes-static-export.md b/errors/api-routes-static-export.md
index d82365e0d324a..8b2388ef561fd 100644
--- a/errors/api-routes-static-export.md
+++ b/errors/api-routes-static-export.md
@@ -4,12 +4,12 @@
An `exportPathMap` path was matched to an API route. Statically exporting a Next.js application via `next export` disables API routes.
-This command is meant for static-only hosts, and is not necessary to make your application static. Pages in your application without server-side data dependencies will be automatically statically exported by `next build`, including pages powered by `getStaticProps`
+This command is meant for a static-only setup, and is not necessary to make your application static. Pages in your application without server-side data dependencies will be automatically statically exported by `next build`, including pages powered by `getStaticProps`
#### Possible Ways to Fix It
-Use `next build` with platforms that don't require `next export` like https://zeit.co or remove any paths using API routes from your `exportPathMap` in `next.config.js`.
+Use `next build` with platforms that don't require `next export` like https://vercel.com or remove any paths using API routes from your `exportPathMap` in `next.config.js`.
### Useful Links
-- [Static HTML export](https://nextjs.org/docs#static-html-export)
+- [Static HTML export](https://nextjs.org/docs/advanced-features/static-html-export)
diff --git a/errors/build-dir-not-writeable.md b/errors/build-dir-not-writeable.md
index 33bf5345f6a1b..98b6f04a20599 100644
--- a/errors/build-dir-not-writeable.md
+++ b/errors/build-dir-not-writeable.md
@@ -2,7 +2,7 @@
#### Why This Error Occurred
-The filesystem does not allow writing to the specified directory. A common cause for this error is starting a [custom server](https://nextjs.org/docs#custom-server-and-routing) in development mode on a production server, for example, [now.sh](https://zeit.co) which [doesn't allow you to write to the filesystem after your app is built](https://zeit.co/docs/deployment-types/node#file-system-specifications).
+The filesystem does not allow writing to the specified directory. A common cause for this error is starting a [custom server](https://nextjs.org/docs/advanced-features/custom-server) in development mode on a production server, for example, [Vercel](https://vercel.com) which doesn't allow you to write to the filesystem after your app is built.
#### Possible Ways to Fix It
@@ -27,4 +27,4 @@ const app = next({ dev })
### Useful Links
-- [Custom Server documentation + examples](https://nextjs.org/docs#custom-server-and-routing)
+- [Custom Server documentation + examples](https://nextjs.org/docs/advanced-features/custom-server)
diff --git a/errors/can-not-output-to-public.md b/errors/can-not-output-to-public.md
index 5a266aeb8fc4c..1423bd329c8dd 100644
--- a/errors/can-not-output-to-public.md
+++ b/errors/can-not-output-to-public.md
@@ -4,7 +4,7 @@
Either you set `distDir` to `public` in your `next.config.js` or during `next export` you tried to export to the `public` directory.
-This is not allowed due to `public` being a special folder in Next.js used to serve static assets.
+This is not allowed because `public` is used by Next.js to serve static assets.
#### Possible Ways to Fix It
@@ -12,4 +12,4 @@ Use a different `distDir` or export to a different folder.
### Useful Links
-- [Static file serving docs](https://nextjs.org/docs#static-file-serving-eg-images)
+- [Static file serving docs](https://nextjs.org/docs/basic-features/static-file-serving)
diff --git a/errors/can-not-output-to-static.md b/errors/can-not-output-to-static.md
new file mode 100644
index 0000000000000..750335e63eef5
--- /dev/null
+++ b/errors/can-not-output-to-static.md
@@ -0,0 +1,15 @@
+# Cannot output to /static
+
+#### Why This Error Occurred
+
+Either you set `distDir` to `static` in your `next.config.js` or during `next export` you tried to export to the `static` directory.
+
+This is not allowed because `static` is used by Next.js to serve static assets.
+
+#### Possible Ways to Fix It
+
+Use a different `distDir` or export to a different folder.
+
+### Useful Links
+
+- [Static file serving docs](https://nextjs.org/docs/basic-features/static-file-serving)
diff --git a/errors/cant-override-next-props.md b/errors/cant-override-next-props.md
index 35bfc02c82f09..3a3773dc46575 100644
--- a/errors/cant-override-next-props.md
+++ b/errors/cant-override-next-props.md
@@ -10,4 +10,4 @@ Look in your \_app.js component's `getInitialProps` function and make sure neith
### Useful Links
-- [The issue this was reported in: #6480](https://github.com/zeit/next.js/issues/6480)
+- [The issue this was reported in: #6480](https://github.com/vercel/next.js/issues/6480)
diff --git a/errors/client-side-exception-occurred.md b/errors/client-side-exception-occurred.md
new file mode 100644
index 0000000000000..06c1dcf5148d1
--- /dev/null
+++ b/errors/client-side-exception-occurred.md
@@ -0,0 +1,14 @@
+# Client-side Exception Occurred
+
+#### Why This Error Occurred
+
+In your production application a client-side error occurred that was not caught by an error boundary. Additional information should be visible in the console tab of your browser.
+
+#### Possible Ways to Fix It
+
+Add error boundaries in your React tree to gracefully handle client-side errors and render a fallback view when they occur.
+
+### Useful Links
+
+- [Error Boundaries Documentation](https://reactjs.org/docs/error-boundaries.html)
+- [Custom Error Page Documentation](https://nextjs.org/docs/advanced-features/custom-error-page#more-advanced-error-page-customizing)
diff --git a/errors/config-resolve-alias.md b/errors/config-resolve-alias.md
index feacf2e3a62eb..4c2c88aa1fcf4 100644
--- a/errors/config-resolve-alias.md
+++ b/errors/config-resolve-alias.md
@@ -19,4 +19,4 @@ webpack(config) {
### Useful Links
-- [Related issue](https://github.com/zeit/next.js/issues/6681)
+- [Related issue](https://github.com/vercel/next.js/issues/6681)
diff --git a/errors/conflicting-public-file-page.md b/errors/conflicting-public-file-page.md
index 3000fdd75fab7..397f34c98360e 100644
--- a/errors/conflicting-public-file-page.md
+++ b/errors/conflicting-public-file-page.md
@@ -28,4 +28,4 @@ pages/
### Useful Links
-- [Static file serving docs](https://nextjs.org/docs#static-file-serving-eg-images)
+- [Static file serving docs](https://nextjs.org/docs/basic-features/static-file-serving)
diff --git a/errors/conflicting-ssg-paths.md b/errors/conflicting-ssg-paths.md
new file mode 100644
index 0000000000000..eb3e71a965bd9
--- /dev/null
+++ b/errors/conflicting-ssg-paths.md
@@ -0,0 +1,68 @@
+# Conflicting SSG Paths
+
+#### Why This Error Occurred
+
+In your `getStaticPaths` function for one of your pages you returned conflicting paths. All page paths must be unique and duplicates are not allowed.
+
+#### Possible Ways to Fix It
+
+Remove any conflicting paths shown in the error message and only return them from one `getStaticPaths`.
+
+Example conflicting paths:
+
+```jsx
+// pages/hello/world.js
+export default function Hello() {
+ return 'hello world!'
+}
+
+// pages/[...catchAll].js
+export const getStaticProps = () => ({ props: {} })
+
+export const getStaticPaths = () => ({
+ paths: [
+ // this conflicts with the /hello/world.js page, remove to resolve error
+ '/hello/world',
+ '/another',
+ ],
+ fallback: false,
+})
+
+export default function CatchAll() {
+ return 'Catch-all page'
+}
+```
+
+Example conflicting paths:
+
+```jsx
+// pages/blog/[slug].js
+export const getStaticPaths = () => ({
+ paths: ['/blog/conflicting', '/blog/another'],
+ fallback: false,
+})
+
+export default function Blog() {
+ return 'Blog!'
+}
+
+// pages/[...catchAll].js
+export const getStaticProps = () => ({ props: {} })
+
+export const getStaticPaths = () => ({
+ paths: [
+ // this conflicts with the /blog/conflicting path above, remove to resolve error
+ '/blog/conflicting',
+ '/another',
+ ],
+ fallback: false,
+})
+
+export default function CatchAll() {
+ return 'Catch-all page'
+}
+```
+
+### Useful Links
+
+- [`getStaticPaths` Documentation](https://nextjs.org/docs/basic-features/data-fetching#getstaticpaths-static-generation)
diff --git a/errors/css-global.md b/errors/css-global.md
index 22c4e87c5e78b..0f2ff4fd84319 100644
--- a/errors/css-global.md
+++ b/errors/css-global.md
@@ -8,10 +8,27 @@ Global CSS cannot be used in files other than your [Custom ``](https://next
#### Possible Ways to Fix It
-Relocate all Global CSS imports to your [`pages/_app.js` file](https://nextjs.org/docs/advanced-features/custom-app).
+To avoid conflicts, relocate all first-party Global CSS imports to your [`pages/_app.js` file](https://nextjs.org/docs/advanced-features/custom-app).
+
+Or, [update your component to use local CSS (Component-Level CSS) via CSS Modules](https://nextjs.org/docs/basic-features/built-in-css-support#adding-component-level-css). This is the preferred approach.
#### Example
+Consider the stylesheet named [`styles.css`](https://nextjs.org/docs/basic-features/built-in-css-support#adding-a-global-stylesheet)
+
+```jsx
+//styles.css
+body {
+ font-family: 'SF Pro Text', 'SF Pro Icons', 'Helvetica Neue', 'Helvetica',
+ 'Arial', sans-serif;
+ padding: 20px 20px 60px;
+ max-width: 680px;
+ margin: 0 auto;
+}
+```
+
+Create a [`pages/_app.js` file](https://nextjs.org/docs/advanced-features/custom-app) if not already present. Then [`import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) the [`styles.css` file](https://nextjs.org/docs/basic-features/built-in-css-support#adding-a-global-stylesheet).
+
```jsx
// pages/_app.js
import '../styles.css'
diff --git a/errors/css-modules-npm.md b/errors/css-modules-npm.md
index c7d86dcd95120..20fe4a579b7cc 100644
--- a/errors/css-modules-npm.md
+++ b/errors/css-modules-npm.md
@@ -21,4 +21,4 @@ imported by you, in your application.
---
If this is **first party code**, try
-[including said monorepo package in the compilation pipeline](https://github.com/zeit/next.js/tree/canary/examples/with-yarn-workspaces).
+[including said monorepo package in the compilation pipeline](https://github.com/vercel/next.js/tree/canary/examples/with-yarn-workspaces).
diff --git a/errors/doc-crossorigin-deprecated.md b/errors/doc-crossorigin-deprecated.md
index 48b99e30013d4..86f16c09794b4 100644
--- a/errors/doc-crossorigin-deprecated.md
+++ b/errors/doc-crossorigin-deprecated.md
@@ -17,4 +17,4 @@ module.exports = {
### Useful Links
-- [The issue this was reported in: #5674](https://github.com/zeit/next.js/issues/5674)
+- [The issue this was reported in: #5674](https://github.com/vercel/next.js/issues/5674)
diff --git a/errors/duplicate-sass.md b/errors/duplicate-sass.md
new file mode 100644
index 0000000000000..aa4e6e9b8b39d
--- /dev/null
+++ b/errors/duplicate-sass.md
@@ -0,0 +1,33 @@
+# Duplicate Sass Dependencies
+
+#### Why This Error Occurred
+
+Your project has a direct dependency on both `sass` and `node-sass`, two
+different package that both compile Sass files!
+
+Next.js will only use one of these, so it is suggested you remove one or the
+other.
+
+#### Possible Ways to Fix It
+
+The `sass` package is a modern implementation of Sass in JavaScript that
+supports all the new features and does not require any native dependencies.
+
+Since `sass` is now the canonical implementation, we suggest removing the older
+`node-sass` package, which should speed up your builds and project install time.
+
+**Via npm**
+
+```bash
+npm uninstall node-sass
+```
+
+**Via Yarn**
+
+```bash
+yarn remove node-sass
+```
+
+### Useful Links
+
+- [`sass` package documentation](https://github.com/sass/dart-sass)
diff --git a/errors/env-loading-disabled.md b/errors/env-loading-disabled.md
new file mode 100644
index 0000000000000..34515e5c1cd4e
--- /dev/null
+++ b/errors/env-loading-disabled.md
@@ -0,0 +1,20 @@
+# Env Loading Disabled
+
+#### Why This Error Occurred
+
+In your project you have `dotenv` listed as a `dependency` or a `devDependency` which opts-out of Next.js' automatic loading to prevent creating a conflict with any existing `dotenv` behavior in your project.
+
+This is also disabled if a `package.json` isn't able to found in your project somehow.
+
+#### Possible Ways to Fix It
+
+Update to the latest version of Next.js (>= v9.4.1) where this support is enabled regardless of `dotenv` being installed.
+
+Remove `dotenv` from your `devDependencies` or `dependencies` and allow Next.js to load your `dotenv` files for you.
+
+### Useful Links
+
+- [dotenv](https://npmjs.com/package/dotenv)
+- [dotenv-expand](https://npmjs.com/package/dotenv-expand)
+- [Environment Variables](https://en.wikipedia.org/wiki/Environment_variable)
+- [Next.js Environment Variables Docs](https://nextjs.org/docs/basic-features/environment-variables)
diff --git a/errors/export-all-in-page.md b/errors/export-all-in-page.md
new file mode 100644
index 0000000000000..c2fe449a8a0bd
--- /dev/null
+++ b/errors/export-all-in-page.md
@@ -0,0 +1,54 @@
+# Re-exporting all exports from a page is disallowed
+
+#### Why This Error Occurred
+
+The following export can potentially break Next.js' compilation of pages:
+
+```ts
+export * from '...'
+```
+
+This is because Node.js code may be leaked to the browser build, causing an error. For example, the following two pages:
+
+```ts
+// pages/one.js
+import fs from 'fs'
+
+export default function A() {
+ return
+}
+
+export function getStaticProps() {
+ fs
+ return { props: {} }
+}
+```
+
+```ts
+// pages/two.js
+export * from './one'
+```
+
+Would cause the following error:
+
+```
+Module not found: Can't resolve 'fs' in './pages/two.js'
+```
+
+#### Possible Ways to Fix It
+
+Update your page to re-export the default component only:
+
+```ts
+export { default } from './other-page'
+```
+
+If the other page uses `getServerSideProps` or `getStaticProps`, you can re-export those individually too:
+
+```ts
+export { default, getServerSideProps } from './other-page'
+// or
+export { default, getStaticProps } from './other-page'
+// or
+export { default, getStaticProps, getStaticPaths } from './other-page/[dynamic]'
+```
diff --git a/errors/export-image-api.md b/errors/export-image-api.md
new file mode 100644
index 0000000000000..dae959c90dcaf
--- /dev/null
+++ b/errors/export-image-api.md
@@ -0,0 +1,24 @@
+# `next export` with Image API
+
+#### Why This Error Occurred
+
+You are attempting to run `next export` while importing the `next/image` component configured using the default `loader`.
+
+However, the default `loader` relies on the Image Optimization API which is not available for exported applications.
+
+This is because Next.js optimizes images on-demand, as users request them (not at build time).
+
+#### Possible Ways to Fix It
+
+- Use `next start` to run a server, which includes the Image Optimization API.
+- 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
+
+- [Deployment Documentation](https://nextjs.org/docs/deployment#vercel-recommended)
+- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
+- [`next export` Documentation](https://nextjs.org/docs/advanced-features/static-html-export)
+- [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image)
+- [Vercel Documentation](https://vercel.com/docs/next.js/image-optimization)
diff --git a/errors/export-no-custom-routes.md b/errors/export-no-custom-routes.md
new file mode 100644
index 0000000000000..9a18c5747e24c
--- /dev/null
+++ b/errors/export-no-custom-routes.md
@@ -0,0 +1,19 @@
+# `next export` No Custom Routes
+
+#### Why This Error Occurred
+
+In your `next.config.js` `rewrites`, `redirects`, or `headers` were defined while `next export` was being run outside of a platform that supports them.
+
+These configs do not apply when exporting your Next.js application manually.
+
+#### Possible Ways to Fix It
+
+Disable the `rewrites`, `redirects`, and `headers` from your `next.config.js` when using `next export` to deploy your application or deploy your application using [a method](https://nextjs.org/docs/deployment#vercel-recommended) that supports these configs.
+
+### Useful Links
+
+- [Deployment Documentation](https://nextjs.org/docs/deployment#vercel-recommended)
+- [`next export` Documentation](https://nextjs.org/docs/advanced-features/static-html-export)
+- [Rewrites Documentation](https://nextjs.org/docs/api-reference/next.config.js/rewrites)
+- [Redirects Documentation](https://nextjs.org/docs/api-reference/next.config.js/redirects)
+- [Headers Documentation](https://nextjs.org/docs/api-reference/next.config.js/headers)
diff --git a/errors/export-path-mismatch.md b/errors/export-path-mismatch.md
index ecf3a75faf116..1900a08b74fb4 100644
--- a/errors/export-path-mismatch.md
+++ b/errors/export-path-mismatch.md
@@ -11,7 +11,7 @@ Change your `exportPathMap` function in `next.config.js` to have a path that mat
```js
module.exports = {
- exportPathMap: function() {
+ exportPathMap: function () {
return {
'/': { page: '/' },
// '/blog/nextjs': { page: '/blog/[post]/comment/[id]' }, // wrong
@@ -23,4 +23,4 @@ module.exports = {
### Useful Links
-- [exportPathMap](https://nextjs.org/docs#usage) documentation
+- [exportPathMap](https://nextjs.org/docs/api-reference/next.config.js/exportPathMap) documentation
diff --git a/errors/future-webpack5-moved-to-webpack5.md b/errors/future-webpack5-moved-to-webpack5.md
new file mode 100644
index 0000000000000..27aadf72a2a85
--- /dev/null
+++ b/errors/future-webpack5-moved-to-webpack5.md
@@ -0,0 +1,33 @@
+# `future.webpack5` has been moved to `webpack5`
+
+#### Why This Error Occurred
+
+The `future.webpack5` option has been moved to `webpack5` in `next.config.js`.
+
+#### Possible Ways to Fix It
+
+If you had the value `true` you can remove the option as webpack 5 is now the default for all Next.js apps unless opted out.
+
+If you had the value `false` you can update `next.config.js`:
+
+Change `future.webpack5` to `webpack5`.
+
+Current `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+ future: {
+ webpack5: false,
+ },
+}
+```
+
+Updated `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+ webpack5: false,
+}
+```
diff --git a/errors/get-initial-props-as-an-instance-method.md b/errors/get-initial-props-as-an-instance-method.md
index fb67e95bea019..26218c66e28eb 100644
--- a/errors/get-initial-props-as-an-instance-method.md
+++ b/errors/get-initial-props-as-an-instance-method.md
@@ -23,7 +23,7 @@ export default class YourEntryComponent extends React.Component {
or
```js
-const YourEntryComponent = function() {
+const YourEntryComponent = function () {
return 'foo'
}
@@ -36,4 +36,4 @@ export default YourEntryComponent
### Useful Links
-- [Fetching data and component lifecycle](https://nextjs.org/docs#fetching-data-and-component-lifecycle)
+- [Fetching data and component lifecycle](https://nextjs.org/docs/api-reference/data-fetching/getInitialProps)
diff --git a/errors/google-font-display.md b/errors/google-font-display.md
new file mode 100644
index 0000000000000..61328e8976282
--- /dev/null
+++ b/errors/google-font-display.md
@@ -0,0 +1,36 @@
+# Google Font Display
+
+### Why This Error Occurred
+
+For a Google Font, the `display` descriptor was either not assigned or set to `auto`, `fallback`, or `block`.
+
+### Possible Ways to Fix It
+
+For most cases, the best font display strategy for custom fonts is `optional`.
+
+```jsx
+import Head from 'next/head'
+
+export default function IndexPage() {
+ return (
+
+}
+```
+
+```js
+// pages/index.js
+// Note how `components/MyComponent` exists but `Mycomponent` without the capital `c` is imported
+import MyComponent from '../components/Mycomponent'
+```
+
+Incorrect casing will lead to build failures on case-sensitive environments like most Linux-based continuous integration and can cause issues with Fast Refresh.
+
+##### The module you're trying to import uses Node.js specific modules
+
+`getStaticProps`, `getStaticPaths`, and `getServerSideProps` allow for using modules that can only run in the Node.js environment. This allows you to do direct database queries or reading data from Redis to name a few examples.
+
+The tree shaking only runs on top level pages, so it can't be relied on in separate React components.
+
+You can verify the tree shaking on [next-code-elimination.vercel.app](https://next-code-elimination.vercel.app/).
+
+Example of correctly tree shaken code:
+
+```js
+// lib/redis.js
+import Redis from 'ioredis'
+
+const redis = new Redis(process.env.REDIS_URL)
+
+export default redis
+```
+
+```js
+// pages/index.js
+import redis from '../lib/redis'
+
+export async function getStaticProps() {
+ const message = await redis.get('message')
+ return {
+ message,
+ }
+}
+
+export default function Home({ message }) {
+ return
{message}
+}
+```
+
+Example of code that would break:
+
+```js
+// lib/redis.js
+import Redis from 'ioredis'
+
+const redis = new Redis(process.env.REDIS_URL)
+
+export default redis
+```
+
+```js
+// pages/index.js
+// Redis is a Node.js specific library that can't run in the browser
+// Trying to use it in code that runs on both Node.js and the browser will result in a module not found error for modules that ioredis relies on
+// If you run into such an error it's recommended to move the code to `getStaticProps` or `getServerSideProps` as those methods guarantee that the code is only run in Node.js.
+import redis from '../lib/redis'
+import { useEffect, useState } from 'react'
+
+export default function Home() {
+ const [message, setMessage] = useState()
+ useEffect(() => {
+ redis.get('message').then((result) => {
+ setMessage(result)
+ })
+ }, [])
+ return
{message}
+}
+```
+
+Example of code that would break:
+
+```js
+// lib/redis.js
+import Redis from 'ioredis'
+
+// Modules that hold Node.js-only code can't also export React components
+// Tree shaking of getStaticProps/getStaticPaths/getServerSideProps is ran only on page files
+const redis = new Redis(process.env.REDIS_URL)
+
+export function MyComponent() {
+ return
Hello
+}
+
+export default redis
+```
+
+```js
+// pages/index.js
+// In practice you'll want to refactor the `MyComponent` to be a separate file so that tree shaking ensures that specific import is not included for the browser compilation
+import redis, { MyComponent } from '../lib/redis'
+
+export async function getStaticProps() {
+ const message = await redis.get('message')
+ return {
+ message,
+ }
+}
+
+export default function Home() {
+ return
+}
+```
diff --git a/errors/nested-reserved-page.md b/errors/nested-reserved-page.md
new file mode 100644
index 0000000000000..69e503effbfa3
--- /dev/null
+++ b/errors/nested-reserved-page.md
@@ -0,0 +1,15 @@
+# Nested Reserved Page
+
+#### Why This Error Occurred
+
+In your pages folder you nested a reserved page e.g. `_app`, `_error`, or `_document` which causes the page to not be used since they must be located directly under the pages folder.
+
+#### Possible Ways to Fix It
+
+Move the reserved pages directly under your pages folder so that they are picked up and used correctly.
+
+### Useful Links
+
+- [Custom `_app` Documentation](https://nextjs.org/docs/advanced-features/custom-app)
+- [Custom `_error` Documentation](https://nextjs.org/docs/advanced-features/custom-error-page)
+- [Custom `_document` Documentation](https://nextjs.org/docs/advanced-features/custom-document)
diff --git a/errors/next-dynamic-modules.md b/errors/next-dynamic-modules.md
index 74838f3029766..a5fa9a1c98bfb 100644
--- a/errors/next-dynamic-modules.md
+++ b/errors/next-dynamic-modules.md
@@ -18,8 +18,8 @@ import dynamic from 'next/dynamic'
const HelloBundle = dynamic({
modules: () => {
const components = {
- Hello1: () => import('../components/hello1').then(m => m.default),
- Hello2: () => import('../components/hello2').then(m => m.default),
+ Hello1: () => import('../components/hello1').then((m) => m.default),
+ Hello2: () => import('../components/hello2').then((m) => m.default),
}
return components
diff --git a/errors/next-export-no-build-id.md b/errors/next-export-no-build-id.md
new file mode 100644
index 0000000000000..affed88c30803
--- /dev/null
+++ b/errors/next-export-no-build-id.md
@@ -0,0 +1,10 @@
+# Could not find a production build
+
+#### Why This Error Occurred
+
+When running `next export` a production build is needed.
+
+#### Possible Ways to Fix It
+
+- Run `next build` to create a production build before running `next export`.
+- If your intention was to run the development server run `next dev` instead.
diff --git a/errors/next-head-count-missing.md b/errors/next-head-count-missing.md
index 78891e0864194..40c040f319461 100644
--- a/errors/next-head-count-missing.md
+++ b/errors/next-head-count-missing.md
@@ -6,6 +6,6 @@ You have a custom `pages/_document.js` that doesn't have the components required
#### Possible Ways to Fix It
-Ensure that your `_document.js` is importing and rendering all of the [required components](https://nextjs.org/docs#custom-document).
+Ensure that your `_document.js` is importing and rendering all of the [required components](https://nextjs.org/docs/advanced-features/custom-document).
In this case you are most likely not rendering the `` component imported from `next/document`.
diff --git a/errors/next-image-missing-loader-width.md b/errors/next-image-missing-loader-width.md
new file mode 100644
index 0000000000000..0df5c6efa7124
--- /dev/null
+++ b/errors/next-image-missing-loader-width.md
@@ -0,0 +1,17 @@
+# Missing `width` in the URL Returned by the Loader Prop on `next/image`
+
+#### Why This Error Occurred
+
+The [`loader`](https://nextjs.org/docs/api-reference/next/image#loader) prop on the `next/image` component allows you to override the built-in URL resolution with a custom implementation in order to support any 3rd party cloud provider that can perform Image Optimization.
+
+This error occurred because the provided `loader()` function did not use `width` in the returned URL string. This means that the image will likely not be resized and therefore degrade performance.
+
+#### Possible Ways to Fix It
+
+- Ensure your Image Optimization provider can resize images. Then use the `width` parameter from the [`loader()`](https://nextjs.org/docs/api-reference/next/image#loader) function to construct the correct URL string.
+- Add the [`unoptimized`](https://nextjs.org/docs/api-reference/next/image#unoptimized) prop.
+
+### Useful Links
+
+- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
+- [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image)
diff --git a/errors/next-image-missing-loader.md b/errors/next-image-missing-loader.md
new file mode 100644
index 0000000000000..9a03dcb26a3d9
--- /dev/null
+++ b/errors/next-image-missing-loader.md
@@ -0,0 +1,15 @@
+# Missing `loader` Prop on `next/image`
+
+#### Why This Error Occurred
+
+When using the `next/image` component with [`loader="custom"`](https://nextjs.org/docs/basic-features/image-optimization#loader) in `next.config.js`, you must provide the [`loader`](https://nextjs.org/docs/api-reference/next/image#loader) prop to the component with your custom implementation.
+
+#### Possible Ways to Fix It
+
+- Add the [`loader`](https://nextjs.org/docs/api-reference/next/image#loader) prop to all usages of the `next/image` component.
+- Change the [`loader`](https://nextjs.org/docs/basic-features/image-optimization#loader) configuration in `next.config.js`.
+
+### Useful Links
+
+- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
+- [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image)
diff --git a/errors/next-image-unconfigured-host.md b/errors/next-image-unconfigured-host.md
new file mode 100644
index 0000000000000..e69525ad03d2b
--- /dev/null
+++ b/errors/next-image-unconfigured-host.md
@@ -0,0 +1,22 @@
+# next/image Un-configured Host
+
+#### Why This Error Occurred
+
+On one of your pages that leverages the `next/image` component, you passed a `src` value that uses a hostname in the URL that isn't defined in the `images.domains` config in `next.config.js`.
+
+#### Possible Ways to Fix It
+
+Add the hostname of your URL to the `images.domains` config in `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+ images: {
+ domains: ['assets.example.com'],
+ },
+}
+```
+
+### Useful Links
+
+- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
diff --git a/errors/next-start-serverless.md b/errors/next-start-serverless.md
index 483f024d99d4c..86009d133d7ea 100644
--- a/errors/next-start-serverless.md
+++ b/errors/next-start-serverless.md
@@ -6,4 +6,4 @@ Next.js can only handle running a server when the `target` is set to `server` (t
#### Possible Ways to Fix It
-Use a different handler than `next start` when testing a serverless **production** build, otherwise just use `next dev`.
+Use a different handler than `next start` when testing a serverless **production** build, otherwise use `next dev`.
diff --git a/errors/no-cache.md b/errors/no-cache.md
index 3951b1901b99a..a580397ef99bd 100644
--- a/errors/no-cache.md
+++ b/errors/no-cache.md
@@ -15,7 +15,7 @@ Configure Next.js' cache to be persisted across builds. Next.js stores its cache
Storing this folder across builds varies by CI provider. We've provided a list of a few common providers below.
-#### ZEIT Now
+#### Vercel
Next.js caching is automatically configured for you. There's no action required on your part.
@@ -60,9 +60,7 @@ cache:
#### Netlify CI
-It is **not possible** to cache custom build files on Netlify. Please contact their support and request they support this behavior.
-
-You can investigate using a 3rd party solution (e.g. [`cache-me-outside`](https://github.com/DavidWells/cache-me-outside)) to manually cache the Next.js output.
+Use [Netlify Plugins](https://www.netlify.com/products/build/plugins/) with [`netlify-plugin-cache-nextjs`](https://www.npmjs.com/package/netlify-plugin-cache-nextjs).
#### AWS CodeBuild
@@ -80,10 +78,14 @@ cache:
Using GitHub's [actions/cache](https://github.com/actions/cache), add the following step in your workflow file:
```yaml
-uses: actions/cache@v1
+uses: actions/cache@v2
with:
path: ${{ github.workspace }}/.next/cache
- key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}
+ # Generate a new cache whenever packages or source files change.
+ key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**.[jt]sx?') }}
+ # If source files changed but packages didn't, rebuild from a prior cache.
+ restore-keys: |
+ ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
```
#### Bitbucket Pipelines
@@ -105,3 +107,23 @@ Then reference it in the `caches` section of your pipeline's `step`:
- node
- nextcache
```
+
+#### Heroku
+
+Using Heroku's [custom cache](https://devcenter.heroku.com/articles/nodejs-support#custom-caching), add a `cacheDirectories` array in your top-level package.json:
+
+```javascript
+"cacheDirectories": [".next/cache"]
+```
+
+#### Azure Pipelines
+
+Using Azure Pipelines' [Cache task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/cache), add the following task to your pipeline yaml file somewhere prior to the task that executes `next build`:
+
+```yaml
+- task: Cache@2
+ displayName: 'Cache .next/cache'
+ inputs:
+ key: next | $(Agent.OS) | yarn.lock
+ path: '$(System.DefaultWorkingDirectory)/.next/cache'
+```
diff --git a/errors/no-css-tags.md b/errors/no-css-tags.md
new file mode 100644
index 0000000000000..8a3e5540402ca
--- /dev/null
+++ b/errors/no-css-tags.md
@@ -0,0 +1,38 @@
+# No CSS Tags
+
+### Why This Error Occurred
+
+An HTML link element was used to link to an external stylesheet. This can negatively affect CSS resource loading on your web page.
+
+### Possible Ways to Fix It
+
+There are multiple ways to include styles using Next.js' built-in CSS support, including the option to use `@import` within the root stylesheet that is imported in `pages/_app.js`:
+
+```css
+/* Root stylesheet */
+@import 'extra.css';
+
+body {
+ /* ... */
+}
+```
+
+Another option is to use CSS Modules to import the CSS file scoped specifically to the component.
+
+```jsx
+import styles from './extra.module.css'
+
+export class Home {
+ render() {
+ return (
+
+
+
+ )
+ }
+}
+```
+
+Refer to the [Built-In CSS Support](https://nextjs.org/docs/basic-features/built-in-css-support) documentation to learn about all the ways to include CSS to your application.
diff --git a/errors/no-document-import-in-page.md b/errors/no-document-import-in-page.md
new file mode 100644
index 0000000000000..8abbf7ceb3d0b
--- /dev/null
+++ b/errors/no-document-import-in-page.md
@@ -0,0 +1,24 @@
+# No Document Import in Page
+
+### Why This Error Occurred
+
+`next/document` was imported in a page outside of `pages/_document.js` (or `pages/_document.tsx` if you are using TypeScript). This can cause unexpected issues in your application.
+
+### Possible Ways to Fix It
+
+Only import and use `next/document` within `pages/_document.js` (or `pages/_document.tsx`) to override the default `Document` component:
+
+```jsx
+// pages/_document.js
+import Document, { Html, Head, Main, NextScript } from 'next/document'
+
+class MyDocument extends Document {
+ //...
+}
+
+export default MyDocument
+```
+
+### Useful Links
+
+- [Custom Document](https://nextjs.org/docs/advanced-features/custom-document)
diff --git a/errors/no-document-title.md b/errors/no-document-title.md
index 62a3cc5d88b0f..e83b856defe92 100644
--- a/errors/no-document-title.md
+++ b/errors/no-document-title.md
@@ -10,36 +10,23 @@ Set `` in `pages/_app.js` instead:
```js
// pages/_app.js
-import App from 'next/app'
-import Head from 'next/head'
import React from 'react'
+import Head from 'next/head'
-export default class MyApp extends App {
- static async getInitialProps({ Component, ctx }) {
- let pageProps = {}
-
- if (Component.getInitialProps) {
- pageProps = await Component.getInitialProps(ctx)
- }
-
- return { pageProps }
- }
-
- render() {
- const { Component, pageProps } = this.props
-
- return (
- <>
- <Head>
- <title>My new cool app
-
-
-
- )
- }
+function MyApp({ Component, pageProps }) {
+ return (
+ <>
+
+ My new cool app
+
+
+
+ )
}
+
+export default MyApp
```
### Useful Links
-- [The issue this was reported in: #4596](https://github.com/zeit/next.js/issues/4596)
+- [The issue this was reported in: #4596](https://github.com/vercel/next.js/issues/4596)
diff --git a/errors/no-document-viewport-meta.md b/errors/no-document-viewport-meta.md
new file mode 100644
index 0000000000000..bf5131b348a24
--- /dev/null
+++ b/errors/no-document-viewport-meta.md
@@ -0,0 +1,32 @@
+# Viewport `meta` tags should not be used in `_document.js`'s ``
+
+#### Why This Error Occurred
+
+Adding `` in `pages/_document.js` will lead to unexpected results since it cannot be deduped.
+The viewport tag should be handled by `next/head` in `pages/_app.js`.
+
+#### Possible Ways to Fix It
+
+Set your viewport `meta` tag in `pages/_app.js` instead:
+
+```tsx
+// pages/_app.js
+import Head from 'next/head'
+
+function MyApp({ Component, pageProps }) {
+ return (
+ <>
+
+
+
+
+
+ )
+}
+
+export default MyApp
+```
+
+### Useful Links
+
+- [Issue #13230](https://github.com/vercel/next.js/issues/13230), which led to the creation of this warning.
diff --git a/errors/no-duplicate-head.md b/errors/no-duplicate-head.md
new file mode 100644
index 0000000000000..ed16c4f102b0d
--- /dev/null
+++ b/errors/no-duplicate-head.md
@@ -0,0 +1,38 @@
+# No Duplicate Head
+
+### Why This Error Occurred
+
+More than a single instance of the `` component was used in a single custom document. This can cause unexpected behavior in your application.
+
+### Possible Ways to Fix It
+
+Only use a single `` component in your custom document in `pages/_document.js`.
+
+```jsx
+// pages/_document.js
+import Document, { Html, Head, Main, NextScript } from 'next/document'
+
+class MyDocument extends Document {
+ static async getInitialProps(ctx) {
+ //...
+ }
+
+ render() {
+ return (
+
+
+
+
+
+
+
+ )
+ }
+}
+
+export default MyDocument
+```
+
+### Useful Links
+
+- [Custom Document](https://nextjs.org/docs/advanced-features/custom-document)
diff --git a/errors/no-head-import-in-document.md b/errors/no-head-import-in-document.md
new file mode 100644
index 0000000000000..9336cff2c8eca
--- /dev/null
+++ b/errors/no-head-import-in-document.md
@@ -0,0 +1,34 @@
+# No Head Import in Document
+
+### Why This Error Occurred
+
+`next/head` was imported in `pages/_document.js`. This can cause unexpected issues in your application.
+
+### Possible Ways to Fix It
+
+Only import and use `next/document` within `pages/_document.js` to override the default `Document` component. If you are importing `next/head` to use the `Head` component, import it from `next/document` instead in order to modify `` code across all pages:
+
+```jsx
+// pages/_document.js
+import Document, { Html, Head, Main, NextScript } from 'next/document'
+
+class MyDocument extends Document {
+ static async getInitialProps(ctx) {
+ //...
+ }
+
+ render() {
+ return (
+
+
+
+ )
+ }
+}
+
+export default MyDocument
+```
+
+### Useful Links
+
+- [Custom Document](https://nextjs.org/docs/advanced-features/custom-document)
diff --git a/errors/no-html-link-for-pages.md b/errors/no-html-link-for-pages.md
new file mode 100644
index 0000000000000..76c8fd8e7bd5b
--- /dev/null
+++ b/errors/no-html-link-for-pages.md
@@ -0,0 +1,45 @@
+# No HTML link for pages
+
+### Why This Error Occurred
+
+An HTML anchor element, ``, was used to navigate to a page route without using the `Link` component.
+
+The `Link` component is required in order to enable client-side route transitions between pages and provide a single-page app experience.
+
+### Possible Ways to Fix It
+
+Make sure to import the `Link` component and wrap anchor elements that route to different page routes.
+
+**Before:**
+
+```jsx
+function Home() {
+ return (
+
+ )
+}
+
+export default Home
+```
+
+### Useful Links
+
+- [next/link API Reference](https://nextjs.org/docs/api-reference/next/link)
diff --git a/errors/no-img-element.md b/errors/no-img-element.md
new file mode 100644
index 0000000000000..96826da88860b
--- /dev/null
+++ b/errors/no-img-element.md
@@ -0,0 +1,32 @@
+# No Img Element
+
+### Why This Error Occurred
+
+An HTML `` element was used to display an image. For better performance and automatic image optimization, use Next.js' built-in image component instead.
+
+### Possible Ways to Fix It
+
+Import and use the `` component:
+
+```jsx
+import Image from 'next/image'
+
+function Home() {
+ return (
+ <>
+
+
+ )
+}
+
+export default Home
+```
+
+### Useful Links
+
+- [Image Component and Image Optimization](https://nextjs.org/docs/basic-features/image-optimization)
diff --git a/errors/no-on-app-updated-hook.md b/errors/no-on-app-updated-hook.md
index c2ce7c5d7eacd..5437cef9d4f71 100644
--- a/errors/no-on-app-updated-hook.md
+++ b/errors/no-on-app-updated-hook.md
@@ -1,11 +1,11 @@
# Router.onAppUpdated is removed
-Due to [this bug fix](https://github.com/zeit/next.js/pull/3849), we had to remove the `Router.onAppUpdated` hook. But the default functionality of this feature is still in effect.
+Due to [this bug fix](https://github.com/vercel/next.js/pull/3849), we had to remove the `Router.onAppUpdated` hook. But the default functionality of this feature is still in effect.
We use this hook to detect a new app deployment when switching pages and act accordingly. Although there are many things you can do in this hook, it's often used to navigate the page via the server as shown below:
```js
-Router.onAppUpdated = function(nextRoute) {
+Router.onAppUpdated = function (nextRoute) {
location.href = nextRoute
}
```
@@ -17,7 +17,7 @@ One real use of this hook is to persist your application state to local-storage
This is code for that:
```js
-window.onbeforeunload = function(e) {
+window.onbeforeunload = function (e) {
// Get the application state (usually from a store like Redux)
const appState = {}
localStorage.setItem('app-state', JSON.stringify(appState))
diff --git a/errors/no-page-custom-font.md b/errors/no-page-custom-font.md
new file mode 100644
index 0000000000000..93766e1d5d36e
--- /dev/null
+++ b/errors/no-page-custom-font.md
@@ -0,0 +1,45 @@
+# No Page Custom Font
+
+### Why This Error Occurred
+
+A custom font was added to a page and not with a custom `Document`. This only adds the font to the specific page and not to the entire application.
+
+### Possible Ways to Fix It
+
+Create the file `./pages/_document.js` and add the font to a custom Document:
+
+```jsx
+// pages/_document.js
+
+import Document, { Html, Head, Main, NextScript } from 'next/document'
+
+class MyDocument extends Document {
+ render() {
+ return (
+
+
+
+
+
+
+
+
+
+ )
+ }
+}
+
+export default MyDocument
+```
+
+### When Not To Use It
+
+If you have a reason to only load a font for a particular page, then you can disable this rule.
+
+### Useful Links
+
+- [Custom Document](https://nextjs.org/docs/advanced-features/custom-document)
+- [Font Optimization](https://nextjs.org/docs/basic-features/font-optimization)
diff --git a/errors/no-router-instance.md b/errors/no-router-instance.md
index 504ce29ecd803..2beaafbc71cbb 100644
--- a/errors/no-router-instance.md
+++ b/errors/no-router-instance.md
@@ -2,8 +2,12 @@
#### Why This Error Occurred
-During SSR you might have tried to access a router method `push`, `replace`, `back`, which is not supported.
+During Pre-rendering (SSR or SSG) you tried to access a router method `push`, `replace`, `back`, which is not supported.
#### Possible Ways to Fix It
-Move any calls to router methods to `componentDidMount` or add a check such as `typeof window !== 'undefined'` before calling the methods
+In a function Component you can move the code into the `useEffect` hook.
+
+In a class Component, move any calls to router methods to the `componentDidMount` lifecycle method.
+
+This way the calls to the router methods are only executed in the browser.
diff --git a/errors/no-sync-scripts.md b/errors/no-sync-scripts.md
new file mode 100644
index 0000000000000..72e9275b6914b
--- /dev/null
+++ b/errors/no-sync-scripts.md
@@ -0,0 +1,30 @@
+# No Sync Scripts
+
+### Why This Error Occurred
+
+A synchronous script was used which can impact your webpage's performance.
+
+### Possible Ways to Fix It
+
+#### Script component (experimental)
+
+Use the Script component with the right loading strategy to defer loading of the script until necessary.
+
+```jsx
+import Script from 'next/script'
+
+const Home = () => {
+ return (
+
+
+
Home Page
+
+ )
+}
+
+export default Home
+```
+
+### Useful Links
+
+- [Efficiently load third-party JavaScript](https://web.dev/efficiently-load-third-party-javascript/)
diff --git a/errors/no-title-in-document-head.md b/errors/no-title-in-document-head.md
new file mode 100644
index 0000000000000..771e99674d5c4
--- /dev/null
+++ b/errors/no-title-in-document-head.md
@@ -0,0 +1,30 @@
+# No Title in Document Head
+
+### Why This Error Occurred
+
+A `` element was defined within the `Head` component imported from `next/document`, which should only be used for any `<head>` code that is common for all pages. Title tags should be defined at the page-level using `next/head`.
+
+### Possible Ways to Fix It
+
+Within a page or component, import and use `next/head` to define a page title:
+
+```jsx
+import Head from 'next/head'
+
+export class Home {
+ render() {
+ return (
+ <div>
+ <Head>
+ <title>My page title
+
+
+ )
+ }
+}
+```
+
+### Useful links
+
+- [next/head](https://nextjs.org/docs/api-reference/next/head)
+- [Custom Document](https://nextjs.org/docs/advanced-features/custom-document)
diff --git a/errors/no-unwanted-polyfillio.md b/errors/no-unwanted-polyfillio.md
new file mode 100644
index 0000000000000..6f05aa9a7251a
--- /dev/null
+++ b/errors/no-unwanted-polyfillio.md
@@ -0,0 +1,13 @@
+# Duplicate Polyfills from Polyfill.io
+
+#### Why This Error Occurred
+
+You are using Polyfill.io and including duplicate polyfills already shipped with Next.js. This increases page weight unnecessarily which can affect loading performance.
+
+#### Possible Ways to Fix It
+
+Remove all duplicate polyfills that are included with Polyfill.io. If you need to add polyfills but are not sure if Next.js already includes it, take a look at the list of [supported browsers and features](https://nextjs.org/docs/basic-features/supported-browsers-features) first.
+
+### Useful Links
+
+- [Supported Browsers and Features](https://nextjs.org/docs/basic-features/supported-browsers-features)
diff --git a/errors/non-dynamic-getstaticpaths-usage.md b/errors/non-dynamic-getstaticpaths-usage.md
new file mode 100644
index 0000000000000..2f94c774b0cab
--- /dev/null
+++ b/errors/non-dynamic-getstaticpaths-usage.md
@@ -0,0 +1,14 @@
+# getStaticPaths Used on Non-Dynamic Page
+
+#### Why This Error Occurred
+
+On a non-dynamic SSG page `getStaticPaths` was incorrectly exported as this can only be used on dynamic pages to return the paths to prerender.
+
+#### Possible Ways to Fix It
+
+Remove the `getStaticPaths` export on the non-dynamic page or rename the page to be a dynamic page.
+
+### Useful Links
+
+- [Dynamic Routes Documentation](https://nextjs.org/docs/routing/dynamic-routes)
+- [`getStaticPaths` Documentation](https://nextjs.org/docs/routing/dynamic-routes)
diff --git a/errors/non-standard-node-env.md b/errors/non-standard-node-env.md
new file mode 100644
index 0000000000000..238823e622dd1
--- /dev/null
+++ b/errors/non-standard-node-env.md
@@ -0,0 +1,29 @@
+# Non-Standard NODE_ENV
+
+#### Why This Error Occurred
+
+Your environment has a non-standard `NODE_ENV` value configured.
+
+This may be by accident, so if you're unaware where the value is coming from, check the following:
+
+- The `.env*` files in your project, if present
+- Your `~/.bash_profile`, if present
+- Your `~/.zshrc`, if present
+
+The greater React ecosystem treats `NODE_ENV` as a convention, only permitting three (3) values:
+
+- `production`: When your application is built with `next build`
+- `development`: When your application is ran with `next dev`
+- `test`: When your application is being tested (e.g. `jest`)
+
+Setting a non-standard `NODE_ENV` value may cause dependencies to behave unexpectedly, or worse, **break dead code elimination**.
+
+#### Possible Ways to Fix It
+
+To fix this error, identify the source of the erroneous `NODE_ENV` value and get rid of it: Next.js automatically sets the correct value for you.
+
+If you need the concept of different environments in your application, e.g. `staging`, you should use a different environment variable name like `APP_ENV`.
+
+### Useful Links
+
+- [Environment Variables](https://en.wikipedia.org/wiki/Environment_variable)
diff --git a/errors/opt-out-auto-static-optimization.md b/errors/opt-out-auto-static-optimization.md
index d4445d444bee3..4c2115e84b957 100644
--- a/errors/opt-out-auto-static-optimization.md
+++ b/errors/opt-out-auto-static-optimization.md
@@ -2,16 +2,18 @@
#### Why This Warning Occurred
-You are using `getInitialProps` in your [Custom ``](https://nextjs.org/docs#custom-app).
+You are using `getInitialProps` in your [Custom ``](https://nextjs.org/docs/advanced-features/custom-app).
-This causes **all non-getStaticProps pages** to be executed on the server -- disabling [Automatic Static Optimization](https://nextjs.org/docs#automatic-static-optimization).
+This causes **all non-getStaticProps pages** to be executed on the server -- disabling [Automatic Static Optimization](https://nextjs.org/docs/advanced-features/automatic-static-optimization).
#### Possible Ways to Fix It
Be sure you meant to use `getInitialProps` in `pages/_app`!
There are some valid use cases for this, but it is often better to handle `getInitialProps` on a _per-page_ basis.
-If you previously copied the [Custom ``](https://nextjs.org/docs#custom-app) example, you may be able to remove your `getInitialProps`.
+Check for any [higher-order components](https://reactjs.org/docs/higher-order-components.html) that may have added `getInitialProps` to your [Custom ``](https://nextjs.org/docs/advanced-features/custom-app).
+
+If you previously copied the [Custom ``](https://nextjs.org/docs/advanced-features/custom-app) example, you may be able to remove your `getInitialProps`.
The following `getInitialProps` does nothing and may be removed:
diff --git a/errors/opt-out-automatic-prerendering.md b/errors/opt-out-automatic-prerendering.md
index afe98e98df4ef..f3db86439cc7f 100644
--- a/errors/opt-out-automatic-prerendering.md
+++ b/errors/opt-out-automatic-prerendering.md
@@ -2,16 +2,16 @@
#### Why This Warning Occurred
-You are using `getInitialProps` in your [Custom ``](https://nextjs.org/docs#custom-app).
+You are using `getInitialProps` in your [Custom ``](https://nextjs.org/docs/advanced-features/custom-app).
-This causes **all pages** to be executed on the server -- disabling [Automatic Static Optimization](https://nextjs.org/docs#automatic-static-optimization).
+This causes **all pages** to be executed on the server -- disabling [Automatic Static Optimization](https://nextjs.org/docs/advanced-features/automatic-static-optimization).
#### Possible Ways to Fix It
Be sure you meant to use `getInitialProps` in `pages/_app`!
There are some valid use cases for this, but it is often better to handle `getInitialProps` on a _per-page_ basis.
-If you previously copied the [Custom ``](https://nextjs.org/docs#custom-app) example, you may be able to remove your `getInitialProps`.
+If you previously copied the [Custom ``](https://nextjs.org/docs/advanced-features/custom-app) example, you may be able to remove your `getInitialProps`.
The following `getInitialProps` does nothing and may be removed:
diff --git a/errors/page-data-collection-timeout.md b/errors/page-data-collection-timeout.md
new file mode 100644
index 0000000000000..12332bfb430be
--- /dev/null
+++ b/errors/page-data-collection-timeout.md
@@ -0,0 +1,18 @@
+# Collecting page data timed out after multiple attempts
+
+#### Why This Error Occurred
+
+Next.js tries to restart the worker pool of the page data collection when no progress happens for a while, to avoid hanging builds.
+
+When restarted it will retry all uncompleted jobs, but if a job was unsuccessfully attempted multiple times, this will lead to an error.
+
+#### Possible Ways to Fix It
+
+- Make sure that there is no infinite loop during execution.
+- Make sure all Promises in `getStaticPaths` `resolve` or `reject` correctly.
+- Avoid very long timeouts for network requests.
+- Increase the timeout by changing the `experimental.pageDataCollectionTimeout` configuration option (default `60` in seconds).
+
+### Useful Links
+
+- [`getStaticPaths`](https://nextjs.org/docs/basic-features/data-fetching#getstaticpaths-static-generation)
diff --git a/errors/page-without-valid-component.md b/errors/page-without-valid-component.md
index 9344b712c9dbb..09d94fee00c35 100644
--- 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/placeholder-blur-data-url.md b/errors/placeholder-blur-data-url.md
new file mode 100644
index 0000000000000..2fc53099c9830
--- /dev/null
+++ b/errors/placeholder-blur-data-url.md
@@ -0,0 +1,15 @@
+# `placeholder=blur` without `blurDataURL`
+
+#### Why This Error Occurred
+
+You are attempting use the `next/image` component with `placeholder=blur` property but no `blurDataURL` property.
+
+The `blurDataURL` might be missing because you're using a string for `src` instead of a static import.
+
+Or `blurDataURL` might be missing because the static import is an unsupported image format. Only jpg, png, and webp are supported at this time.
+
+#### Possible Ways to Fix It
+
+- Add a [`blurDataURL`](https://nextjs.org/docs/api-reference/next/image#blurdataurl) property, the contents should be a small Data URL to represent the image
+- Change the [`src`](https://nextjs.org/docs/api-reference/next/image#src) property to a static import with one of the supported file types: jpg, png, or webp
+- Remove the [`placeholder`](https://nextjs.org/docs/api-reference/next/image#placeholder) property, effectively no blur effect
diff --git a/errors/popstate-state-empty.md b/errors/popstate-state-empty.md
index 433adc2287a5a..ccd98713a557d 100644
--- a/errors/popstate-state-empty.md
+++ b/errors/popstate-state-empty.md
@@ -2,13 +2,13 @@
#### Why This Error Occurred
-When using the browser back button the popstate event is triggered. Next.js sets
-`popstate` event triggered but `event.state` did not have `url` or `as`, causing a route change failure
+When using the browser back button the popstate event is triggered. Next.js sees a
+`popstate` event being triggered but `event.state` did not have `url` or `as`, causing a route change failure.
#### Possible Ways to Fix It
-The only known cause of this issue is manually manipulating `window.history` instead of using `next/router`
+The only known cause of this issue is manually manipulating `window.history` instead of using `next/router`. Starting from version 9.5, Next.js will ignore `popstate` events that contain `event.state` not created by its own router.
### Useful Links
-- [The issue this was reported in: #4994](https://github.com/zeit/next.js/issues/4994)
+- [The issue this was reported in: #4994](https://github.com/vercel/next.js/issues/4994)
diff --git a/errors/postcss-ignored-plugin.md b/errors/postcss-ignored-plugin.md
index 658ad57f28575..e8c73f1c69965 100644
--- a/errors/postcss-ignored-plugin.md
+++ b/errors/postcss-ignored-plugin.md
@@ -17,4 +17,4 @@ Remove the plugin specified in the error message from your custom PostCSS config
#### How do I configure CSS Modules?
CSS Modules are supported in [Next.js' built-in CSS support](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
-You can [read more](https://nextjs.org/docs/advanced-features/customizing-postcss-config) about how to use them [here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
+You can [read more about how to use CSS Modules here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
diff --git a/errors/postcss-shape.md b/errors/postcss-shape.md
index 889fe55bcbc68..f121c889d04b1 100644
--- a/errors/postcss-shape.md
+++ b/errors/postcss-shape.md
@@ -39,7 +39,7 @@ module.exports = {
}
```
-You can [read more](https://nextjs.org/docs/advanced-features/customizing-postcss-config) about configuring PostCSS in Next.js [here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
+You can [read more about configuring PostCSS in Next.js here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
#### Common Errors
diff --git a/errors/prefetch-true-deprecated.md b/errors/prefetch-true-deprecated.md
index dbc5a2ed346f4..77733fea94726 100644
--- a/errors/prefetch-true-deprecated.md
+++ b/errors/prefetch-true-deprecated.md
@@ -18,4 +18,4 @@ These requests have low-priority and yield to fetch() or XHR requests. Next.js w
The prefetch attribute is no longer needed, when set to true, example: `prefetch={true}`, remove the property.
-Prefetching can be disabled with `prefetch={false}`.
+Prefetching can be turned off with `prefetch={false}`.
diff --git a/errors/prerender-error.md b/errors/prerender-error.md
index 207671f546490..87e301c459db6 100644
--- a/errors/prerender-error.md
+++ b/errors/prerender-error.md
@@ -7,5 +7,7 @@ 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
+- Make sure your component handles `fallback` if it is enabled in `getStaticPaths`. [Fallback docs](https://nextjs.org/docs/basic-features/data-fetching#the-fallback-key-required)
+- Make sure you are not trying to export (`next export`) pages that have server-side rendering enabled [(getServerSideProps)](https://nextjs.org/docs/basic-features/data-fetching#getserversideprops-server-side-rendering)
diff --git a/errors/production-start-no-build-id.md b/errors/production-start-no-build-id.md
new file mode 100644
index 0000000000000..c6c9bfdb93f57
--- /dev/null
+++ b/errors/production-start-no-build-id.md
@@ -0,0 +1,10 @@
+# Could not find a production build
+
+#### Why This Error Occurred
+
+When running `next start` or a custom server in production mode a production build is needed.
+
+#### Possible Ways to Fix It
+
+- Run `next build` to create a production build before booting up the production server.
+- If your intention was to run the development server run `next dev` instead.
diff --git a/errors/promise-in-next-config.md b/errors/promise-in-next-config.md
index 7fb48b3b00419..f39ce7786fc78 100644
--- a/errors/promise-in-next-config.md
+++ b/errors/promise-in-next-config.md
@@ -6,7 +6,7 @@ The webpack function in `next.config.js` returned a promise which is not support
```js
module.exports = {
- webpack: async function(config) {
+ webpack: async function (config) {
return config
},
}
diff --git a/errors/react-version.md b/errors/react-version.md
new file mode 100644
index 0000000000000..713254102491b
--- /dev/null
+++ b/errors/react-version.md
@@ -0,0 +1,51 @@
+# Minimum React Version
+
+#### Why This Error Occurred
+
+Your project is using an old version of `react` or `react-dom` that does not
+meet the suggested minimum version requirement.
+
+Next.js suggests using, at a minimum, `react@17.0.2` and `react-dom@17.0.2`.
+Older versions of `react` and `react-dom` do work with Next.js, however, they do
+not enable all of Next.js' features.
+
+For example, the following features are not enabled with old React versions:
+
+- [Fast Refresh](https://nextjs.org/docs/basic-features/fast-refresh): instantly
+ view edits to your app without losing component state
+- Component stack trace in development: see the component tree that lead up to
+ an error
+- Hydration mismatch warnings: trace down discrepancies in your React tree that
+ cause performance problems
+
+This list is not exhaustive, but illustrative in the value of upgrading React!
+
+#### Possible Ways to Fix It
+
+**Via npm**
+
+```bash
+npm upgrade react@latest react-dom@latest
+```
+
+**Via Yarn**
+
+```bash
+yarn add react@latest react-dom@latest
+```
+
+**Manually** Open your `package.json` and upgrade `react` and `react-dom`:
+
+```json
+{
+ "dependencies": {
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2"
+ }
+}
+```
+
+### Useful Links
+
+- [Fast Refresh blog post](https://nextjs.org/blog/next-9-4#fast-refresh)
+- [Fast Refresh docs](https://nextjs.org/docs/basic-features/fast-refresh)
diff --git a/errors/rewrite-auto-export-fallback.md b/errors/rewrite-auto-export-fallback.md
new file mode 100644
index 0000000000000..a16fa7125639d
--- /dev/null
+++ b/errors/rewrite-auto-export-fallback.md
@@ -0,0 +1,18 @@
+# Rewriting to Auto Export or Fallback Dynamic Route
+
+#### Why This Error Occurred
+
+One of your rewrites in your `next.config.js` point to a [dynamic route](https://nextjs.org/docs/routing/dynamic-routes) that is automatically statically optimized or is a [fallback SSG page](https://nextjs.org/docs/basic-features/data-fetching#the-fallback-key-required).
+
+Rewriting to these pages are not yet supported since rewrites are not available client-side and the dynamic route params are unable to be parsed. Support for this may be added in a future release.
+
+#### Possible Ways to Fix It
+
+For fallback SSG pages you can add the page to the list of [prerendered paths](https://nextjs.org/docs/basic-features/data-fetching#the-paths-key-required).
+
+For static dynamic routes, you will currently need to either rewrite to non-dynamic route or opt the page out of the static optimization with [`getServerSideProps`](https://nextjs.org/docs/basic-features/data-fetching#getserversideprops-server-side-rendering)
+
+### Useful Links
+
+- [Dynamic Routes Documentation](https://nextjs.org/docs/routing/dynamic-routes)
+- [Fallback Documentation](https://nextjs.org/docs/basic-features/data-fetching#the-fallback-key-required)
diff --git a/errors/routes-must-be-array.md b/errors/routes-must-be-array.md
index fd4a909dc111c..59b1875653ec6 100644
--- a/errors/routes-must-be-array.md
+++ b/errors/routes-must-be-array.md
@@ -13,13 +13,11 @@ Make sure to return an array that contains the routes.
```js
// next.config.js
module.exports = {
- experimental: {
- async rewrites() {
- return {
- source: '/feedback',
- destination: '/feedback/general',
- }
- },
+ async rewrites() {
+ return {
+ source: '/feedback',
+ destination: '/feedback/general',
+ }
},
}
```
@@ -28,15 +26,13 @@ module.exports = {
```js
module.exports = {
- experimental: {
- async rewrites() {
- return [
- {
- source: '/feedback',
- destination: '/feedback/general',
- },
- ]
- },
+ async rewrites() {
+ return [
+ {
+ source: '/feedback',
+ destination: '/feedback/general',
+ },
+ ]
},
}
```
diff --git a/errors/sharp-missing-in-production.md b/errors/sharp-missing-in-production.md
new file mode 100644
index 0000000000000..01fc602b4b4e3
--- /dev/null
+++ b/errors/sharp-missing-in-production.md
@@ -0,0 +1,13 @@
+# Sharp Missing In Production
+
+#### Why This Error Occurred
+
+The `next/image` component's default loader uses the ['squoosh'](https://www.npmjs.com/package/@squoosh/lib) library for image resizing and optimization. This library is quick to install and suitable for a dev server environment. For a production environment, it is strongly recommended that you install the optional [`sharp`](https://www.npmjs.com/package/sharp). This package was not detected when leveraging the Image Optimization in production mode (`next start`).
+
+#### Possible Ways to Fix It
+
+Install `sharp` by running `yarn add sharp` in your project directory.
+
+### Useful Links
+
+- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
diff --git a/errors/ssg-fallback-true-export.md b/errors/ssg-fallback-true-export.md
new file mode 100644
index 0000000000000..9696edc817d71
--- /dev/null
+++ b/errors/ssg-fallback-true-export.md
@@ -0,0 +1,14 @@
+# SSG `fallback: true` Export Error
+
+#### Why This Error Occurred
+
+You attempted to export a page with a `fallback: true` return value from `getStaticPaths` which is invalid. `fallback: true` is meant for building pages on-demand after a build has occurred, exporting disables this functionality
+
+#### Possible Ways to Fix It
+
+If you would like the `fallback: true` behavior, `next export` should not be used. Instead follow the [deployment documentation](https://nextjs.org/docs/deployment) to deploy your incrementally generated static site.
+
+### Useful Links
+
+- [deployment documentation](https://nextjs.org/docs/deployment#vercel-recommended)
+- [`fallback: true` documentation](https://nextjs.org/docs/basic-features/data-fetching#fallback-true)
diff --git a/errors/static-dir-deprecated.md b/errors/static-dir-deprecated.md
index 303e7311c8b48..76e13986aed9a 100644
--- a/errors/static-dir-deprecated.md
+++ b/errors/static-dir-deprecated.md
@@ -8,11 +8,11 @@ The reason we want to support a `public` directory instead is to not require the
#### Possible Ways to Fix It
-You can move your `static` directory inside of the `public` directory and all URLs will remain the same as they were before.
+You can move your `static` directory inside of the `public` directory and all URLs will stay the same as they were before.
**Before**
-```sh
+```
static/
my-image.jpg
pages/
@@ -23,7 +23,7 @@ components/
**After**
-```sh
+```
public/
static/
my-image.jpg
@@ -35,4 +35,4 @@ components/
### Useful Links
-- [Static file serving docs](https://nextjs.org/docs#static-file-serving-eg-images)
+- [Static file serving docs](https://nextjs.org/docs/basic-features/static-file-serving)
diff --git a/errors/static-page-generation-timeout.md b/errors/static-page-generation-timeout.md
new file mode 100644
index 0000000000000..604e0364870f5
--- /dev/null
+++ b/errors/static-page-generation-timeout.md
@@ -0,0 +1,18 @@
+# Static page generation timed out after multiple attempts
+
+#### Why This Error Occurred
+
+Next.js tries to restart the worker pool of the static page generation when no progress happens for a while, to avoid hanging builds.
+
+When restarted it will retry all uncompleted jobs, but if a job was unsuccessfully attempted multiple times, this will lead to an error.
+
+#### Possible Ways to Fix It
+
+- Make sure that there is no infinite loop during execution.
+- Make sure all Promises in `getStaticProps` `resolve` or `reject` correctly.
+- Avoid very long timeouts for network requests.
+- Increase the timeout by changing the `experimental.staticPageGenerationTimeout` configuration option (default `60` in seconds).
+
+### Useful Links
+
+- [`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation)
diff --git a/errors/template.md b/errors/template.md
new file mode 100644
index 0000000000000..711da0c52abf2
--- /dev/null
+++ b/errors/template.md
@@ -0,0 +1,13 @@
+#
+
+#### Why This Error Occurred
+
+
+
+#### Possible Ways to Fix It
+
+
+
+### Useful Links
+
+
diff --git a/errors/undefined-webpack-config.md b/errors/undefined-webpack-config.md
new file mode 100644
index 0000000000000..fb15fdb731ba9
--- /dev/null
+++ b/errors/undefined-webpack-config.md
@@ -0,0 +1,28 @@
+# Missing webpack config
+
+#### Why This Error Occurred
+
+The value returned from the custom `webpack` function in your `next.config.js` was undefined. This can occur from the initial config value not being returned.
+
+#### Possible Ways to Fix It
+
+Make sure to return the `webpack` config from your custom `webpack` function in your `next.config.js`
+
+```js
+// next.config.js
+
+module.exports = {
+ webpack: (config, { buildId, dev, isServer, defaultLoaders, webpack }) => {
+ // Note: we provide webpack above so you should not `require` it
+ // Perform customizations to webpack config
+ config.plugins.push(new webpack.IgnorePlugin(/\/__tests__\//))
+
+ // Important: return the modified config
+ return config
+ },
+}
+```
+
+### Useful Links
+
+- [Custom webpack config Documentation](https://nextjs.org/docs/api-reference/next.config.js/custom-webpack-config)
diff --git a/errors/url-deprecated.md b/errors/url-deprecated.md
index d583128789469..df352d8e07068 100644
--- a/errors/url-deprecated.md
+++ b/errors/url-deprecated.md
@@ -10,9 +10,9 @@ The reason this is going away is that we want to make things very predictable an
#### Possible Ways to Fix It
-https://github.com/zeit/next-codemod#url-to-withrouter
+https://nextjs.org/docs/advanced-features/codemods#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`:
@@ -33,4 +33,4 @@ export default withRouter(Page)
We provide a codemod (a code to code transformation) to automatically change the `url` property usages to `withRouter`.
-You can find this codemod and instructions on how to run it here: https://github.com/zeit/next-codemod#url-to-withrouter
+You can find this codemod and instructions on how to run it here: https://nextjs.org/docs/advanced-features/codemods#url-to-withrouter
diff --git a/errors/webpack5.md b/errors/webpack5.md
new file mode 100644
index 0000000000000..b8c994c549e3a
--- /dev/null
+++ b/errors/webpack5.md
@@ -0,0 +1,45 @@
+# Webpack 5 Adoption
+
+#### Why This Message Occurred
+
+Next.js has adopted webpack 5 as the default for compilation. We've spent a lot of effort into ensuring the transition from webpack 4 to 5 will be as smooth as possible. For example Next.js now comes with both webpack 4 and 5 allowing you to adopt webpack 5 by adding a flag to your `next.config.js`:
+
+```js
+module.exports = {
+ // Webpack 5 is enabled by default
+ // You can still use webpack 4 while upgrading to the latest version of Next.js by adding the "webpack5: false" flag
+ webpack5: false,
+}
+```
+
+Using webpack 5 in your application has many benefits, notably:
+
+- Improved Disk Caching: `next build` is significantly faster on subsequent builds
+- Improved Fast Refresh: Fast Refresh work is prioritized
+- Improved Long Term Caching of Assets: Deterministic code output that is less likely to change between builds
+- Improved Tree Shaking
+- Support for assets using `new URL("file.png", import.meta.url)`
+- Support for web workers using `new Worker(new URL("worker.js", import.meta.url))`
+- Support for `exports`/`imports` field in `package.json`
+
+In the past releases we have gradually rolled out webpack 5 to Next.js applications:
+
+- In Next.js 10.2 we automatically opted-in applications without custom webpack configuration in `next.config.js`
+- In Next.js 10.2 we automatically opted-in applications that do not have a `next.config.js`
+- In Next.js 11 webpack 5 was enabled by default for all applications. You can still opt-out and use webpack 4 to help with backwards compatibility using `webpack5: false` in `next.config.js`
+
+In the next major version webpack 4 support will be removed.
+
+#### Custom webpack configuration
+
+In case you do have custom webpack configuration, either through custom plugins or your own modifications you'll have to take a few steps to ensure your applications works with webpack 5.
+
+- When using `next-transpile-modules` make sure you use the latest version which includes [this patch](https://github.com/martpie/next-transpile-modules/pull/179)
+- When using `@zeit/next-css` / `@zeit/next-sass` make sure you use the [built-in CSS/Sass support](https://nextjs.org/docs/basic-features/built-in-css-support) instead
+- When using `@zeit/next-preact` use [this example](https://github.com/vercel/next-plugins/tree/master/packages/next-preact) instead
+- When using `@zeit/next-source-maps` use the [built-in production Source Map support](https://nextjs.org/docs/advanced-features/source-maps)
+- When using webpack plugins make sure they're upgraded to the latest version, in most cases the latest version will include webpack 5 support. In some cases these upgraded webpack plugins will only support webpack 5.
+
+### Useful Links
+
+In case you're running into issues you can connect with the community in [this help discussion](https://github.com/vercel/next.js/discussions/23498).
diff --git a/examples/active-class-name/.gitignore b/examples/active-class-name/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ 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/active-class-name/README.md b/examples/active-class-name/README.md
index 115a0ed889305..902d79e24b7fe 100644
--- a/examples/active-class-name/README.md
+++ b/examples/active-class-name/README.md
@@ -2,41 +2,26 @@
ReactRouter has a convenience property on the `Link` element to allow an author to set the _active_ className on a link. This example replicates that functionality using Next's own `Link`.
-## Deploy your own
-
-Deploy the example using [ZEIT Now](https://zeit.co/now):
+## Preview
-[](https://zeit.co/import/project?template=https://github.com/zeit/next.js/tree/canary/examples/active-class-name)
-
-## How to use
+Preview the example live on [StackBlitz](http://stackblitz.com/):
-### Using `create-next-app`
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/active-class-name)
-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
-npm init next-app --example active-class-name active-class-name-app
-# or
-yarn create next-app --example active-class-name active-class-name-app
-```
+## Deploy your own
-### Download manually
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-Download the example:
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/active-class-name&project-name=active-class-name&repository-name=active-class-name)
-```bash
-curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/active-class-name
-cd active-class-name
-```
+## How to use
-Install it and run:
+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
-npm install
-npm run dev
+npx create-next-app --example active-class-name active-class-name-app
# or
-yarn
-yarn dev
+yarn create next-app --example active-class-name active-class-name-app
```
-Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+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)).
diff --git a/examples/active-class-name/components/ActiveLink.js b/examples/active-class-name/components/ActiveLink.js
index e9a87243d5baa..0db59b6a9227a 100644
--- a/examples/active-class-name/components/ActiveLink.js
+++ b/examples/active-class-name/components/ActiveLink.js
@@ -4,12 +4,15 @@ import Link from 'next/link'
import React, { Children } from 'react'
const ActiveLink = ({ children, activeClassName, ...props }) => {
- const { pathname } = useRouter()
+ const { asPath } = useRouter()
const child = Children.only(children)
const childClassName = child.props.className || ''
+ // pages/index.js will be matched via props.href
+ // pages/about.js will be matched via props.href
+ // pages/[slug].js will be matched via props.as
const className =
- pathname === props.href
+ asPath === props.href || asPath === props.as
? `${childClassName} ${activeClassName}`.trim()
: childClassName
diff --git a/examples/active-class-name/components/Nav.js b/examples/active-class-name/components/Nav.js
index 32e15a23466c2..2c710bb42468f 100644
--- a/examples/active-class-name/components/Nav.js
+++ b/examples/active-class-name/components/Nav.js
@@ -22,6 +22,11 @@ const Nav = () => (
About
+
+
+ )
+}
+
+export default SlugPage
diff --git a/examples/amp-first/.gitignore b/examples/amp-first/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ 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
diff --git a/examples/amp-first/README.md b/examples/amp-first/README.md
index 0cd5438142b21..4db9d29709f07 100644
--- a/examples/amp-first/README.md
+++ b/examples/amp-first/README.md
@@ -1,6 +1,6 @@
# AMP First Boilerplate ⚡
-This example sets up the boilerplate for an AMP First Site. You can see a live version [here](https://my-next-app.sebastianbenz.now.sh). The boilerplate includes the following features:
+This example sets up the boilerplate for an AMP First Site. You can see a [live version here](https://my-next-app.sebastianbenz.vercel.app). The boilerplate includes the following features:
- AMP Extension helpers (`amp-state`, `amp-script`, ...)
- AMP Serviceworker integration
@@ -9,41 +9,20 @@ This example sets up the boilerplate for an AMP First Site. You can see a live v
## Deploy your own
-Deploy the example using [ZEIT Now](https://zeit.co/now):
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-[](https://zeit.co/import/project?template=https://github.com/zeit/next.js/tree/canary/examples/amp-first)
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/amp-first&project-name=amp-first&repository-name=amp-first)
## 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:
+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
-npm init next-app --example amp-first amp-first-app
+npx create-next-app --example amp-first amp-first-app
# or
yarn create next-app --example amp-first amp-first-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/amp-first
-cd amp-first
-```
-
-Install it and run:
-
-```bash
-npm install
-npm run dev
-# or
-yarn
-yarn dev
-```
-
Open [http://localhost:3000](http://localhost:3000) to view it in the browser. The page will reload if you make edits. You will also see AMP validation errors in the console.
## Todo
@@ -81,7 +60,7 @@ Things you need to do after installing the boilerplate:
```
- **amp-list & amp-mustache:** mustache templates conflict with JSX and it's template literals need to be escaped. A simple approach is to escape them via back ticks: `` src={`{{imageUrl}}`} ``.
-- **amp-script:** you can use [amp-script](https://amp.dev/documentation/components/amp-script/) to add custom JavaScript to your AMP pages. The boilerplate includes a helper [`components/amp/AmpScript.js`](components/amp/AmpScript.js) to simplify using amp-script. The helper also supports embedding inline scripts. Good to know: Next.js uses [AMP Optimizer](https://github.com/ampproject/amp-toolbox/tree/master/packages/optimizer) under the hood, which automatically adds the needed script hashes for [inline amp-scripts](https://amp.dev/documentation/components/amp-script/#load-javascript-from-a-local-element).
+- **amp-script:** you can use [amp-script](https://amp.dev/documentation/components/amp-script/) to add custom JavaScript to your AMP pages. The boilerplate includes a helper [`components/amp/AmpScript.js`](components/amp/AmpScript.js) to simplify using `amp-script`. The helper also supports embedding inline scripts. Good to know: Next.js uses [AMP Optimizer](https://github.com/ampproject/amp-toolbox/tree/master/packages/optimizer) under the hood, which automatically adds the needed script hashes for [inline amp-scripts](https://amp.dev/documentation/components/amp-script/#load-javascript-from-a-local-element).
## Deployment
@@ -97,4 +76,4 @@ To start the application in production mode, run:
$ yarn start
```
-Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+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)).
diff --git a/examples/amp-first/components/Layout.js b/examples/amp-first/components/Layout.js
index 6abebffa4d376..8653c88488a33 100644
--- a/examples/amp-first/components/Layout.js
+++ b/examples/amp-first/components/Layout.js
@@ -10,7 +10,7 @@ const THEME_COLOR = '#005af0'
*
* @param {Props} props
*/
-const Layout = props => (
+const Layout = (props) => (
<>
{props.title || ''}
diff --git a/examples/amp-first/package.json b/examples/amp-first/package.json
index c30040c7d230b..4f6934191388f 100644
--- a/examples/amp-first/package.json
+++ b/examples/amp-first/package.json
@@ -1,6 +1,5 @@
{
- "name": "amp-first",
- "version": "1.0.0",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build",
@@ -8,8 +7,8 @@
},
"dependencies": {
"next": "latest",
- "react": "^16.10.2",
- "react-dom": "^16.10.2"
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2"
},
- "license": "ISC"
+ "license": "MIT"
}
diff --git a/examples/amp-first/pages/index.js b/examples/amp-first/pages/index.js
index 6518d49e8d108..38d8aab91fc08 100644
--- a/examples/amp-first/pages/index.js
+++ b/examples/amp-first/pages/index.js
@@ -1,4 +1,3 @@
-import React from 'react'
import Layout from '../components/Layout'
import AmpState from '../components/amp/AmpState'
import AmpScript from '../components/amp/AmpScript'
@@ -9,7 +8,7 @@ import {
export const config = { amp: true }
-const Home = props => (
+const Home = (props) => (
<>
(
@@ -235,7 +234,7 @@ const Home = props => (
// amp-script requires absolute URLs, so we create a property `host` which we can use to calculate the script URL.
export async function getServerSideProps({ req }) {
- // WARNING: This is a generally unsafe application unless you're deploying to a managed platform like ZEIT Now.
+ // WARNING: This is a generally unsafe application unless you're deploying to a managed platform like Vercel.
// Be sure your load balancer is configured to not allow spoofed host headers.
return { props: { host: `${getProtocol(req)}://${req.headers.host}` } }
}
diff --git a/examples/amp-first/pages/offline.js b/examples/amp-first/pages/offline.js
index 9a31b13122de4..ec987b8882d63 100644
--- a/examples/amp-first/pages/offline.js
+++ b/examples/amp-first/pages/offline.js
@@ -1,4 +1,3 @@
-import React from 'react'
import Layout from '../components/Layout'
export const config = { amp: true }
diff --git a/examples/amp-story/.gitignore b/examples/amp-story/.gitignore
index 1f1d31514a8f2..1437c53f70bc2 100644
--- a/examples/amp-story/.gitignore
+++ b/examples/amp-story/.gitignore
@@ -1,3 +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
-.next
-node_modules
+*.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-story/README.md b/examples/amp-story/README.md
index 6e05c2d42bd75..008980bf3214f 100644
--- a/examples/amp-story/README.md
+++ b/examples/amp-story/README.md
@@ -4,39 +4,18 @@ This example shows how to create an AMP page with `amp-story` using Next.js and
## Deploy your own
-Deploy the example using [ZEIT Now](https://zeit.co/now):
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-[](https://zeit.co/import/project?template=https://github.com/zeit/next.js/tree/canary/examples/amp-story)
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/amp-story&project-name=amp-story&repository-name=amp-story)
## 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
-npm init next-app --example amp-story amp-app
-# or
-yarn create next-app --example amp-story amp-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/amp-story
-cd amp-story
-```
-
-Install it and run:
+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
-npm install
-npm run dev
+npx create-next-app --example amp-story amp-story-app
# or
-yarn
-yarn dev
+yarn create next-app --example amp-story amp-story-app
```
-Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+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)).
diff --git a/examples/amp-story/package.json b/examples/amp-story/package.json
index c5b61de231dd7..4f6934191388f 100644
--- a/examples/amp-story/package.json
+++ b/examples/amp-story/package.json
@@ -1,6 +1,5 @@
{
- "name": "amp-story",
- "version": "1.0.0",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build",
@@ -8,8 +7,8 @@
},
"dependencies": {
"next": "latest",
- "react": "^16.7.0",
- "react-dom": "^16.7.0"
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2"
},
- "license": "ISC"
+ "license": "MIT"
}
diff --git a/examples/amp-story/pages/index.js b/examples/amp-story/pages/index.js
index d7b9e05dcca31..7446873a848ea 100644
--- a/examples/amp-story/pages/index.js
+++ b/examples/amp-story/pages/index.js
@@ -2,122 +2,124 @@ import Head from 'next/head'
export const config = { amp: true }
-export default () => (
- <>
-
- Example AMP Story in Next.js
-
-
-
+export default function Home() {
+ return (
+ <>
+
+ Example AMP Story in Next.js
+
+
+
-
- {/* */}
-
-
-
-
-
-
+
+
- {/* */}
-
-
-
-
-
-
-
+ {/* */}
+
+
+
+
+
+
+
- {/* */}
-
-
-
-)
+ {/* */}
+
+
+
+ )
+}
diff --git a/examples/amp/.gitignore b/examples/amp/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ b/examples/amp/.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/README.md b/examples/amp/README.md
index faf96be3ed42c..33aa31b3684e5 100644
--- a/examples/amp/README.md
+++ b/examples/amp/README.md
@@ -4,39 +4,18 @@ This example shows how to create AMP pages using Next.js and the AMP feature. It
## Deploy your own
-Deploy the example using [ZEIT Now](https://zeit.co/now):
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-[](https://zeit.co/import/project?template=https://github.com/zeit/next.js/tree/canary/examples/amp)
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/amp&project-name=amp&repository-name=amp)
## 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:
+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
-npm init next-app --example amp amp-app
+npx create-next-app --example amp amp-app
# or
yarn create next-app --example amp amp-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/amp
-cd amp
-```
-
-Install it and run:
-
-```bash
-npm install
-npm run dev
-# or
-yarn
-yarn dev
-```
-
-Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+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)).
diff --git a/examples/amp/components/Byline.js b/examples/amp/components/Byline.js
index af93c93e11185..64f34a8135f17 100644
--- a/examples/amp/components/Byline.js
+++ b/examples/amp/components/Byline.js
@@ -1,11 +1,13 @@
-export default ({ author }) => (
- <>
-
+
+
+ )
+}
diff --git a/examples/amp/package.json b/examples/amp/package.json
index 906426c7a4eec..4f6934191388f 100644
--- a/examples/amp/package.json
+++ b/examples/amp/package.json
@@ -1,6 +1,5 @@
{
- "name": "amp",
- "version": "1.0.0",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build",
@@ -8,8 +7,8 @@
},
"dependencies": {
"next": "latest",
- "react": "^16.7.0",
- "react-dom": "^16.7.0"
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2"
},
- "license": "ISC"
+ "license": "MIT"
}
diff --git a/examples/amp/pages/dog.js b/examples/amp/pages/dog.js
index 5c4b41e82dfc5..168d2681a59d4 100644
--- a/examples/amp/pages/dog.js
+++ b/examples/amp/pages/dog.js
@@ -6,7 +6,7 @@ export const config = {
amp: 'hybrid',
}
-export default () => {
+export default function DogPage() {
const isAmp = useAmp()
return (
diff --git a/examples/amp/pages/index.js b/examples/amp/pages/index.js
index f7952214e0f1f..5395cb8f9ee6b 100644
--- a/examples/amp/pages/index.js
+++ b/examples/amp/pages/index.js
@@ -7,7 +7,7 @@ export const config = {
amp: true,
}
-export default () => {
+export default function IndexPage() {
const isAmp = useAmp()
return (
@@ -77,7 +77,7 @@ export default () => {
food, yet ignore the squirrels, you'll never catch them anyway cat
snacks spread kitty litter all over house or hopped up on catnip. Spit
up on light gray carpet instead of adjacent linoleum throwup on your
- pillow, so cat is love, cat is life yet human is washing you why halp oh
+ pillow, so cat is love, cat is life yet human is washing you why help oh
the horror flee scratch hiss bite. Chase mice. Swat turds around the
house hide at bottom of staircase to trip human. Meowing non stop for
food howl on top of tall thing. Shake treat bag pee in human's bed until
@@ -93,7 +93,7 @@ export default () => {
catch the red dot today slap owner's face at 5am until human fills food
dish scratch at the door then walk away for intrigued by the shower, but
steal the warm chair right after you get up. Fall asleep on the washing
- machine destroy couch as revenge scream at teh bath so love to play with
+ machine destroy couch as revenge scream at the bath so love to play with
owner's hair tie. Howl uncontrollably for no reason rub whiskers on bare
skin act innocent. Cats making all the muffins lick butt and make a
weird face meow all night having their mate disturbing sleeping humans
@@ -108,7 +108,7 @@ export default () => {
cleans the litter box and if it fits, i sits caticus cuteicus. Eats
owners hair then claws head lounge in doorway, and hide when guests come
over chase ball of string eat owner's food play riveting piece on
- synthesizer keyboard. Purrr purr littel cat, little cat purr purr spit
+ synthesizer keyboard. Purrr purr little cat, little cat purr purr spit
up on light gray carpet instead of adjacent linoleum kitty loves pigs
yet damn that dog meow or walk on car leaving trail of paw prints on
hood and windshield. Roll on the floor purring your whiskers off meow
@@ -212,7 +212,7 @@ export default () => {
together yet have my breakfast spaghetti yarn so scamper. Need to chase
tail meow for food, then when human fills food dish, take a few bites of
food and continue meowing for pee in the shoe thinking longingly about
- tuna brine yet purrr purr littel cat, little cat purr purr lie on your
+ tuna brine yet purrr purr little cat, little cat purr purr lie on your
belly and purr when you are asleep. Lounge in doorway poop on grasses
for lounge in doorway for chew iPad power cord.
diff --git a/examples/amp/pages/normal.js b/examples/amp/pages/normal.js
index 7a3f6f14ff697..a2868d2da0416 100644
--- a/examples/amp/pages/normal.js
+++ b/examples/amp/pages/normal.js
@@ -1 +1,3 @@
-export default () =>
I'm just a normal old page, no AMP for me
+export default function NormalPage() {
+ return
I'm just a normal old page, no AMP for me
+}
diff --git a/examples/analyze-bundles/.gitignore b/examples/analyze-bundles/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ b/examples/analyze-bundles/.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/analyze-bundles/README.md b/examples/analyze-bundles/README.md
index 1d43af0c8e99c..8aec1e56c79c4 100644
--- a/examples/analyze-bundles/README.md
+++ b/examples/analyze-bundles/README.md
@@ -1,50 +1,43 @@
# Analyzer Bundles example
-This example shows how to analyze the output bundles using [@next/bundle-analyzer](https://github.com/zeit/next.js/tree/master/packages/next-bundle-analyzer)
+This example shows how to analyze the output bundles using [@next/bundle-analyzer](https://github.com/vercel/next.js/tree/master/packages/next-bundle-analyzer)
+
+## Preview
+
+Preview the example live on [StackBlitz](http://stackblitz.com/):
+
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/analyze-bundles)
## Deploy your own
-Deploy the example using [ZEIT Now](https://zeit.co/now):
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-[](https://zeit.co/import/project?template=https://github.com/zeit/next.js/tree/canary/examples/analyze-bundles)
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/analyze-bundles&project-name=analyze-bundles&repository-name=analyze-bundles)
## 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:
+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
-npm init next-app --example analyze-bundles analyze-bundles-app
+npx create-next-app --example analyze-bundles analyze-bundles-app
# or
yarn create next-app --example analyze-bundles analyze-bundles-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/analyze-bundles
-cd analyze-bundles
-```
+### Analyze webpack output
-Install it
+To analyze your webpack output, invoke the following command:
```bash
-npm install
-npm run dev
+npm run analyze
# or
-yarn
-yarn dev
+yarn analyze
```
-### Analyze webpack output
-
-To analyze your webpack output, invoke the following command:
+Once the build is completed, you can inspect the bundle by running:
```bash
-npm run analyze
+npm run serve
# or
-yarn analyze
+yarn serve
```
diff --git a/examples/analyze-bundles/package.json b/examples/analyze-bundles/package.json
index 49db7282fda0e..cf68f1de51ac2 100644
--- a/examples/analyze-bundles/package.json
+++ b/examples/analyze-bundles/package.json
@@ -1,19 +1,22 @@
{
- "name": "with-webpack-bundle-analyzer",
- "version": "1.0.0",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start",
- "analyze": "cross-env ANALYZE=true yarn build"
+ "analyze": "cross-env ANALYZE=true yarn build",
+ "serve": "serve .next/analyze"
},
"dependencies": {
"@next/bundle-analyzer": "^9.1.4",
"cross-env": "^6.0.3",
"faker": "^4.1.0",
"next": "latest",
- "react": "^16.8.0",
- "react-dom": "^16.8.0"
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2"
},
- "license": "ISC"
+ "devDependencies": {
+ "serve": "^11.3.2"
+ },
+ "license": "MIT"
}
diff --git a/examples/analyze-bundles/pages/about.js b/examples/analyze-bundles/pages/about.js
index 5fd65c2baf2cb..46817af02a5c1 100644
--- a/examples/analyze-bundles/pages/about.js
+++ b/examples/analyze-bundles/pages/about.js
@@ -1 +1,3 @@
-export default () =>
+}
diff --git a/examples/analyze-bundles/pages/index.js b/examples/analyze-bundles/pages/index.js
index c40a24da07b18..7d4d8aa18a3ae 100644
--- a/examples/analyze-bundles/pages/index.js
+++ b/examples/analyze-bundles/pages/index.js
@@ -1,4 +1,3 @@
-import React from 'react'
import Link from 'next/link'
import faker from 'faker'
diff --git a/examples/api-routes-apollo-server-and-client-auth/.env b/examples/api-routes-apollo-server-and-client-auth/.env
new file mode 100644
index 0000000000000..f7448eb30a792
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client-auth/.env
@@ -0,0 +1,3 @@
+# Secrets like the one below should go into `.env.local` instead to avoid pushing
+# them to a repository, this is an exception for the sake of the example
+TOKEN_SECRET="this-is-a-secret-value-with-at-least-32-characters"
\ No newline at end of file
diff --git a/examples/api-routes-apollo-server-and-client-auth/.gitignore b/examples/api-routes-apollo-server-and-client-auth/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client-auth/.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/api-routes-apollo-server-and-client-auth/README.md b/examples/api-routes-apollo-server-and-client-auth/README.md
index 269a82d59b823..6385acf21368a 100644
--- a/examples/api-routes-apollo-server-and-client-auth/README.md
+++ b/examples/api-routes-apollo-server-and-client-auth/README.md
@@ -1,43 +1,29 @@
# Apollo Server and Client Auth Example
-[Apollo](https://www.apollographql.com/client/) is a GraphQL client that allows you to easily query the exact data you need from a GraphQL server. In addition to fetching and mutating data, Apollo analyzes your queries and their results to construct a client-side cache of your data, which is kept up to date as further queries and mutations are run, fetching more results from the server.
+[Apollo](https://www.apollographql.com/client/) is a GraphQL client that allows you to easily query the exact data you need from a GraphQL server. In addition to fetching and mutating data, Apollo analyzes your queries and their results to construct a client-side cache of your data, which is kept up to date as further queries and mutations are run.
-In this simple example, we integrate Apollo seamlessly with Next by wrapping our _pages/\_app.js_ inside a [higher-order component (HOC)](https://facebook.github.io/react/docs/higher-order-components.html). Using the HOC pattern we're able to pass down a central store of query result data created by Apollo into our React component hierarchy defined inside each page of our Next application.
+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.
-On initial page load, while on the server and inside `getInitialProps`, we invoke the Apollo method, [`getDataFromTree`](https://www.apollographql.com/docs/react/api/react-ssr/#getdatafromtree). This method returns a promise; at the point in which the promise resolves, our Apollo Client store is completely initialized.
+## Preview
-Note: Do not be alarmed that you see two renders being executed. Apollo recursively traverses the React render tree looking for Apollo query components. When it has done that, it fetches all these queries and then passes the result to a cache. This cache is then used to render the data on the server side (another React render).
-https://www.apollographql.com/docs/react/api/react-ssr/#getdatafromtree
+Preview the example live on [StackBlitz](http://stackblitz.com/):
-## How to use
-
-### Using `create-next-app`
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-apollo-server-and-client-auth)
-Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example:
+## Deploy your own
-```bash
-npx create-next-app --example api-routes-apollo-server-and-client-auth api-routes-apollo-server-and-client-auth-app
-# or
-yarn create next-app --example api-routes-apollo-server-and-client-auth api-routes-apollo-server-and-client-auth-app
-```
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-### Download manually
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-apollo-server-and-client-auth&project-name=api-routes-apollo-server-and-client-auth&repository-name=api-routes-apollo-server-and-client-auth)
-Download the example:
-
-```bash
-curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/api-routes-apollo-server-and-client-auth
-cd api-routes-apollo-server-and-client-auth
-```
+## How to use
-Install it and run:
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example:
```bash
-npm install
-npm run dev
+npx create-next-app --example api-routes-apollo-server-and-client-auth api-routes-apollo-server-and-client-auth-app
# or
-yarn
-yarn dev
+yarn create next-app --example api-routes-apollo-server-and-client-auth api-routes-apollo-server-and-client-auth-app
```
-> If you have issues installing `bcrypt`, follow this instructions: https://github.com/kelektiv/node.bcrypt.js/wiki/Installation-Instructions
+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)).
diff --git a/examples/api-routes-apollo-server-and-client-auth/apollo/client.js b/examples/api-routes-apollo-server-and-client-auth/apollo/client.js
index 55135ad4eb17c..87aa90e97f71c 100644
--- a/examples/api-routes-apollo-server-and-client-auth/apollo/client.js
+++ b/examples/api-routes-apollo-server-and-client-auth/apollo/client.js
@@ -1,152 +1,55 @@
-import React from 'react'
-import Head from 'next/head'
-import { ApolloProvider } from '@apollo/react-hooks'
-import { ApolloClient } from 'apollo-client'
-import { InMemoryCache } from 'apollo-cache-inmemory'
+import { useMemo } from 'react'
+import { ApolloClient, InMemoryCache } from '@apollo/client'
+import merge from 'deepmerge'
-let globalApolloClient = null
+let apolloClient
-/**
- * Creates and provides the apolloContext
- * to a next.js PageTree. Use it by wrapping
- * your PageComponent via HOC pattern.
- * @param {Function|Class} PageComponent
- * @param {Object} [config]
- * @param {Boolean} [config.ssr=true]
- */
-export function withApollo(PageComponent, { ssr = true } = {}) {
- const WithApollo = ({ apolloClient, apolloState, ...pageProps }) => {
- const client = apolloClient || initApolloClient(undefined, apolloState)
- return (
-
-
-
- )
- }
-
- // Set the correct displayName in development
- if (process.env.NODE_ENV !== 'production') {
- const displayName =
- PageComponent.displayName || PageComponent.name || 'Component'
-
- if (displayName === 'App') {
- console.warn('This withApollo HOC only works with PageComponents.')
- }
-
- WithApollo.displayName = `withApollo(${displayName})`
- }
-
- if (ssr || PageComponent.getInitialProps) {
- WithApollo.getInitialProps = async ctx => {
- const { AppTree } = ctx
-
- // Initialize ApolloClient, add it to the ctx object so
- // we can use it in `PageComponent.getInitialProp`.
- const apolloClient = (ctx.apolloClient = initApolloClient({
- res: ctx.res,
- req: ctx.req,
- }))
-
- // Run wrapped getInitialProps methods
- let pageProps = {}
- if (PageComponent.getInitialProps) {
- pageProps = await PageComponent.getInitialProps(ctx)
- }
-
- // Only on the server:
- if (typeof window === 'undefined') {
- // When redirecting, the response is finished.
- // No point in continuing to render
- if (ctx.res && ctx.res.finished) {
- return pageProps
- }
-
- // Only if ssr is enabled
- if (ssr) {
- try {
- // Run all GraphQL queries
- const { getDataFromTree } = await import('@apollo/react-ssr')
- await getDataFromTree(
-
- )
- } catch (error) {
- // Prevent Apollo Client GraphQL errors from crashing SSR.
- // Handle them in components via the data.error prop:
- // https://www.apollographql.com/docs/react/api/react-apollo.html#graphql-query-data-error
- console.error('Error while running `getDataFromTree`', error)
- }
-
- // getDataFromTree does not call componentWillUnmount
- // head side effect therefore need to be cleared manually
- Head.rewind()
- }
- }
-
- // Extract query data from the Apollo store
- const apolloState = apolloClient.cache.extract()
-
- return {
- ...pageProps,
- apolloState,
- }
- }
- }
-
- return WithApollo
-}
-
-/**
- * Always creates a new apollo client on the server
- * Creates or reuses apollo client in the browser.
- * @param {Object} initialState
- */
-function initApolloClient(ctx, initialState) {
- // Make sure to create a new client for every server-side request so that data
- // isn't shared between connections (which would be bad)
+function createIsomorphLink() {
if (typeof window === 'undefined') {
- return createApolloClient(ctx, initialState)
- }
-
- // Reuse client on the client-side
- if (!globalApolloClient) {
- globalApolloClient = createApolloClient(ctx, initialState)
+ const { SchemaLink } = require('@apollo/client/link/schema')
+ const { schema } = require('./schema')
+ return new SchemaLink({ schema })
+ } else {
+ const { HttpLink } = require('@apollo/client/link/http')
+ return new HttpLink({
+ uri: '/api/graphql',
+ credentials: 'same-origin',
+ })
}
-
- return globalApolloClient
}
-/**
- * Creates and configures the ApolloClient
- * @param {Object} [initialState={}]
- */
-function createApolloClient(ctx = {}, initialState = {}) {
- const ssrMode = typeof window === 'undefined'
- const cache = new InMemoryCache().restore(initialState)
-
- // Check out https://github.com/zeit/next.js/pull/4611 if you want to use the AWSAppSyncClient
+function createApolloClient() {
return new ApolloClient({
- ssrMode,
- link: createIsomorphLink(ctx),
- cache,
+ ssrMode: typeof window === 'undefined',
+ link: createIsomorphLink(),
+ cache: new InMemoryCache(),
})
}
-function createIsomorphLink(ctx) {
- if (typeof window === 'undefined') {
- const { SchemaLink } = require('apollo-link-schema')
- const { schema } = require('./schema')
- return new SchemaLink({ schema, context: ctx })
- } else {
- const { HttpLink } = require('apollo-link-http')
+export function initializeApollo(initialState = null) {
+ const _apolloClient = apolloClient ?? createApolloClient()
- return new HttpLink({
- uri: '/api/graphql',
- credentials: 'same-origin',
- })
+ // If your page has Next.js data fetching methods that use Apollo Client, the initial state
+ // get hydrated here
+ if (initialState) {
+ // Get existing cache, loaded during client side data fetching
+ const existingCache = _apolloClient.extract()
+
+ // Merge the existing cache into data passed from getStaticProps/getServerSideProps
+ const data = merge(initialState, existingCache)
+
+ // Restore the cache with the merged data
+ _apolloClient.cache.restore(data)
}
+ // For SSG and SSR always create a new Apollo Client
+ if (typeof window === 'undefined') return _apolloClient
+ // Create the Apollo Client once in the client
+ if (!apolloClient) apolloClient = _apolloClient
+
+ return _apolloClient
+}
+
+export function useApollo(initialState) {
+ const store = useMemo(() => initializeApollo(initialState), [initialState])
+ return store
}
diff --git a/examples/api-routes-apollo-server-and-client-auth/apollo/resolvers.js b/examples/api-routes-apollo-server-and-client-auth/apollo/resolvers.js
index 76e6d851cdba0..4dafa4d5a8ed5 100644
--- a/examples/api-routes-apollo-server-and-client-auth/apollo/resolvers.js
+++ b/examples/api-routes-apollo-server-and-client-auth/apollo/resolvers.js
@@ -1,76 +1,39 @@
import { AuthenticationError, UserInputError } from 'apollo-server-micro'
-import cookie from 'cookie'
-import jwt from 'jsonwebtoken'
-import getConfig from 'next/config'
-import bcrypt from 'bcrypt'
-import v4 from 'uuid/v4'
-
-const JWT_SECRET = getConfig().serverRuntimeConfig.JWT_SECRET
-
-const users = []
-
-function createUser(data) {
- const salt = bcrypt.genSaltSync()
-
- return {
- id: v4(),
- email: data.email,
- hashedPassword: bcrypt.hashSync(data.password, salt),
- }
-}
-
-function validPassword(user, password) {
- return bcrypt.compareSync(password, user.hashedPassword)
-}
+import { createUser, findUser, validatePassword } from '../lib/user'
+import { setLoginSession, getLoginSession } from '../lib/auth'
+import { removeTokenCookie } from '../lib/auth-cookies'
export const resolvers = {
Query: {
async viewer(_parent, _args, context, _info) {
- const { token } = cookie.parse(context.req.headers.cookie ?? '')
- if (token) {
- try {
- const { id, email } = jwt.verify(token, JWT_SECRET)
+ try {
+ const session = await getLoginSession(context.req)
- return users.find(user => user.id === id && user.email === email)
- } catch {
- throw new AuthenticationError(
- 'Authentication token is invalid, please log in'
- )
+ if (session) {
+ return findUser({ email: session.email })
}
+ } catch (error) {
+ throw new AuthenticationError(
+ 'Authentication token is invalid, please log in'
+ )
}
},
},
Mutation: {
async signUp(_parent, args, _context, _info) {
- const user = createUser(args.input)
-
- users.push(user)
-
+ const user = await createUser(args.input)
return { user }
},
-
async signIn(_parent, args, context, _info) {
- const user = users.find(user => user.email === args.input.email)
+ const user = await findUser({ email: args.input.email })
- if (user && validPassword(user, args.input.password)) {
- const token = jwt.sign(
- { email: user.email, id: user.id, time: new Date() },
- JWT_SECRET,
- {
- expiresIn: '6h',
- }
- )
+ if (user && (await validatePassword(user, args.input.password))) {
+ const session = {
+ id: user.id,
+ email: user.email,
+ }
- context.res.setHeader(
- 'Set-Cookie',
- cookie.serialize('token', token, {
- httpOnly: true,
- maxAge: 6 * 60 * 60,
- path: '/',
- sameSite: 'lax',
- secure: process.env.NODE_ENV === 'production',
- })
- )
+ await setLoginSession(context.res, session)
return { user }
}
@@ -78,17 +41,7 @@ export const resolvers = {
throw new UserInputError('Invalid email and password combination')
},
async signOut(_parent, _args, context, _info) {
- context.res.setHeader(
- 'Set-Cookie',
- cookie.serialize('token', '', {
- httpOnly: true,
- maxAge: -1,
- path: '/',
- sameSite: 'lax',
- secure: process.env.NODE_ENV === 'production',
- })
- )
-
+ removeTokenCookie(context.res)
return true
},
},
diff --git a/examples/api-routes-apollo-server-and-client-auth/apollo/type-defs.js b/examples/api-routes-apollo-server-and-client-auth/apollo/type-defs.js
index cd77f1e5b26e7..e9ae131763228 100644
--- a/examples/api-routes-apollo-server-and-client-auth/apollo/type-defs.js
+++ b/examples/api-routes-apollo-server-and-client-auth/apollo/type-defs.js
@@ -1,9 +1,10 @@
-import gql from 'graphql-tag'
+import { gql } from '@apollo/client'
export const typeDefs = gql`
type User {
id: ID!
email: String!
+ createdAt: Int!
}
input SignUpInput {
diff --git a/examples/api-routes-apollo-server-and-client-auth/components/field.js b/examples/api-routes-apollo-server-and-client-auth/components/field.js
index 5ad6fa2e3548e..c33baa1e17ec6 100644
--- a/examples/api-routes-apollo-server-and-client-auth/components/field.js
+++ b/examples/api-routes-apollo-server-and-client-auth/components/field.js
@@ -1,20 +1,16 @@
-export default function Field(props) {
+export default function Field({ name, label, type, autoComplete, required }) {
return (
-
)
diff --git a/examples/api-routes-apollo-server-and-client-auth/lib/auth-cookies.js b/examples/api-routes-apollo-server-and-client-auth/lib/auth-cookies.js
new file mode 100644
index 0000000000000..b0fbf5030b7ec
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client-auth/lib/auth-cookies.js
@@ -0,0 +1,41 @@
+import { serialize, parse } from 'cookie'
+
+const TOKEN_NAME = 'token'
+
+export const MAX_AGE = 60 * 60 * 8 // 8 hours
+
+export function setTokenCookie(res, token) {
+ const cookie = serialize(TOKEN_NAME, token, {
+ maxAge: MAX_AGE,
+ expires: new Date(Date.now() + MAX_AGE * 1000),
+ httpOnly: true,
+ secure: process.env.NODE_ENV === 'production',
+ path: '/',
+ sameSite: 'lax',
+ })
+
+ res.setHeader('Set-Cookie', cookie)
+}
+
+export function removeTokenCookie(res) {
+ const cookie = serialize(TOKEN_NAME, '', {
+ maxAge: -1,
+ path: '/',
+ })
+
+ res.setHeader('Set-Cookie', cookie)
+}
+
+export function parseCookies(req) {
+ // For API Routes we don't need to parse the cookies.
+ if (req.cookies) return req.cookies
+
+ // For pages we do need to parse the cookies.
+ const cookie = req.headers?.cookie
+ return parse(cookie || '')
+}
+
+export function getTokenCookie(req) {
+ const cookies = parseCookies(req)
+ return cookies[TOKEN_NAME]
+}
diff --git a/examples/api-routes-apollo-server-and-client-auth/lib/auth.js b/examples/api-routes-apollo-server-and-client-auth/lib/auth.js
new file mode 100644
index 0000000000000..fe830e95d5e45
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client-auth/lib/auth.js
@@ -0,0 +1,29 @@
+import Iron from '@hapi/iron'
+import { MAX_AGE, setTokenCookie, getTokenCookie } from './auth-cookies'
+
+const TOKEN_SECRET = process.env.TOKEN_SECRET
+
+export async function setLoginSession(res, session) {
+ const createdAt = Date.now()
+ // Create a session object with a max age that we can validate later
+ const obj = { ...session, createdAt, maxAge: MAX_AGE }
+ const token = await Iron.seal(obj, TOKEN_SECRET, Iron.defaults)
+
+ setTokenCookie(res, token)
+}
+
+export async function getLoginSession(req) {
+ const token = getTokenCookie(req)
+
+ if (!token) return
+
+ const session = await Iron.unseal(token, TOKEN_SECRET, Iron.defaults)
+ const expiresAt = session.createdAt + session.maxAge * 1000
+
+ // Validate the expiration date of the session
+ if (Date.now() > expiresAt) {
+ throw new Error('Session expired')
+ }
+
+ return session
+}
diff --git a/examples/api-routes-apollo-server-and-client-auth/lib/user.js b/examples/api-routes-apollo-server-and-client-auth/lib/user.js
new file mode 100644
index 0000000000000..df9b1fca53939
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client-auth/lib/user.js
@@ -0,0 +1,46 @@
+import crypto from 'crypto'
+import { v4 as uuidv4 } from 'uuid'
+
+/**
+ * User methods. The example doesn't contain a DB, but for real applications you must use a
+ * db here, such as MongoDB, Fauna, SQL, etc.
+ */
+
+const users = []
+
+export async function createUser({ email, password }) {
+ // Here you should create the user and save the salt and hashed password (some dbs may have
+ // authentication methods that will do it for you so you don't have to worry about it):
+ const salt = crypto.randomBytes(16).toString('hex')
+ const hash = crypto
+ .pbkdf2Sync(password, salt, 1000, 64, 'sha512')
+ .toString('hex')
+ const user = {
+ id: uuidv4(),
+ createdAt: Date.now(),
+ email,
+ hash,
+ salt,
+ }
+
+ // This is an in memory store for users, there is no data persistence without a proper DB
+ users.push(user)
+
+ return user
+}
+
+// Here you should lookup for the user in your DB
+export async function findUser({ email }) {
+ // This is an in memory store for users, there is no data persistence without a proper DB
+ return users.find((user) => user.email === email)
+}
+
+// Compare the password of an already fetched user (using `findUser`) and compare the
+// password for a potential match
+export async function validatePassword(user, inputPassword) {
+ const inputHash = crypto
+ .pbkdf2Sync(inputPassword, user.salt, 1000, 64, 'sha512')
+ .toString('hex')
+ const passwordsMatch = user.hash === inputHash
+ return passwordsMatch
+}
diff --git a/examples/api-routes-apollo-server-and-client-auth/next.config.js b/examples/api-routes-apollo-server-and-client-auth/next.config.js
deleted file mode 100644
index 35db685d842d2..0000000000000
--- a/examples/api-routes-apollo-server-and-client-auth/next.config.js
+++ /dev/null
@@ -1,5 +0,0 @@
-module.exports = {
- serverRuntimeConfig: {
- JWT_SECRET: 'changeme',
- },
-}
diff --git a/examples/api-routes-apollo-server-and-client-auth/package.json b/examples/api-routes-apollo-server-and-client-auth/package.json
index cc147e35e06fe..e021b87f28417 100644
--- a/examples/api-routes-apollo-server-and-client-auth/package.json
+++ b/examples/api-routes-apollo-server-and-client-auth/package.json
@@ -1,32 +1,22 @@
{
- "name": "with-apollo",
- "version": "2.0.0",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start"
},
"dependencies": {
- "@apollo/react-common": "3.1.3",
- "@apollo/react-hooks": "3.1.3",
- "@apollo/react-ssr": "3.1.3",
- "apollo-cache-inmemory": "1.6.5",
- "apollo-client": "2.6.8",
- "apollo-link-http": "1.5.16",
- "apollo-link-schema": "1.2.4",
- "apollo-server-micro": "2.9.16",
- "apollo-utilities": "^1.3.2",
- "bcrypt": "3.0.7",
- "cookie": "0.4.0",
+ "@apollo/client": "^3.0.2",
+ "@hapi/iron": "6.0.0",
+ "apollo-server-micro": "^2.14.2",
+ "cookie": "^0.4.1",
+ "deepmerge": "4.2.2",
"graphql": "^14.0.2",
- "graphql-tag": "2.10.1",
- "jsonwebtoken": "8.5.1",
"next": "latest",
"prop-types": "^15.6.2",
- "react": "^16.7.0",
- "react-dom": "^16.7.0",
- "uuid": "3.4.0"
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2",
+ "uuid": "8.1.0"
},
- "author": "",
- "license": "ISC"
+ "license": "MIT"
}
diff --git a/examples/api-routes-apollo-server-and-client-auth/pages/_app.js b/examples/api-routes-apollo-server-and-client-auth/pages/_app.js
new file mode 100644
index 0000000000000..482728ae76e6d
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client-auth/pages/_app.js
@@ -0,0 +1,12 @@
+import { ApolloProvider } from '@apollo/client'
+import { useApollo } from '../apollo/client'
+
+export default function App({ Component, pageProps }) {
+ const apolloClient = useApollo(pageProps.initialApolloState)
+
+ return (
+
+
+
+ )
+}
diff --git a/examples/api-routes-apollo-server-and-client-auth/pages/about.js b/examples/api-routes-apollo-server-and-client-auth/pages/about.js
index 37a11a9e09651..36ce20fa93b79 100644
--- a/examples/api-routes-apollo-server-and-client-auth/pages/about.js
+++ b/examples/api-routes-apollo-server-and-client-auth/pages/about.js
@@ -1,11 +1,13 @@
import Link from 'next/link'
-export default () => (
-
- This is a static page goto{' '}
-
- dynamic
- {' '}
- page.
-
-)
+export default function About() {
+ return (
+
+ Welcome to the about page. Go to the{' '}
+
+ Home
+ {' '}
+ page.
+
}
- if (data && data.viewer) {
+ if (viewer) {
return (
- You're signed in as {data.viewer.email} goto{' '}
+ You're signed in as {viewer.email} goto{' '}
- static
+ about
{' '}
page. or{' '}
@@ -43,4 +47,4 @@ const Index = () => {
return
Loading...
}
-export default withApollo(Index)
+export default Index
diff --git a/examples/api-routes-apollo-server-and-client-auth/pages/signin.js b/examples/api-routes-apollo-server-and-client-auth/pages/signin.js
index 766a4bd2ca415..59349fb0e57dc 100644
--- a/examples/api-routes-apollo-server-and-client-auth/pages/signin.js
+++ b/examples/api-routes-apollo-server-and-client-auth/pages/signin.js
@@ -1,11 +1,10 @@
-import React from 'react'
+import { useState } from 'react'
+import { useRouter } from 'next/router'
import Link from 'next/link'
-import { withApollo } from '../apollo/client'
-import gql from 'graphql-tag'
-import { useMutation, useApolloClient } from '@apollo/react-hooks'
-import Field from '../components/field'
+import { gql } from '@apollo/client'
+import { useMutation, useApolloClient } from '@apollo/client'
import { getErrorMessage } from '../lib/form'
-import { useRouter } from 'next/router'
+import Field from '../components/field'
const SignInMutation = gql`
mutation SignInMutation($email: String!, $password: String!) {
@@ -21,7 +20,7 @@ const SignInMutation = gql`
function SignIn() {
const client = useApolloClient()
const [signIn] = useMutation(SignInMutation)
- const [errorMsg, setErrorMsg] = React.useState()
+ const [errorMsg, setErrorMsg] = useState()
const router = useRouter()
async function handleSubmit(event) {
@@ -66,7 +65,7 @@ function SignIn() {
label="Password"
/>
or{' '}
-
+
Sign up
@@ -74,4 +73,4 @@ function SignIn() {
)
}
-export default withApollo(SignIn)
+export default SignIn
diff --git a/examples/api-routes-apollo-server-and-client-auth/pages/signout.js b/examples/api-routes-apollo-server-and-client-auth/pages/signout.js
index 0d18c89827816..046310db75e77 100644
--- a/examples/api-routes-apollo-server-and-client-auth/pages/signout.js
+++ b/examples/api-routes-apollo-server-and-client-auth/pages/signout.js
@@ -1,8 +1,6 @@
-import React from 'react'
-import { useMutation, useApolloClient } from '@apollo/react-hooks'
-import gql from 'graphql-tag'
+import { useEffect } from 'react'
import { useRouter } from 'next/router'
-import { withApollo } from '../apollo/client'
+import { gql, useMutation, useApolloClient } from '@apollo/client'
const SignOutMutation = gql`
mutation SignOutMutation {
@@ -15,7 +13,7 @@ function SignOut() {
const router = useRouter()
const [signOut] = useMutation(SignOutMutation)
- React.useEffect(() => {
+ useEffect(() => {
signOut().then(() => {
client.resetStore().then(() => {
router.push('/signin')
@@ -26,4 +24,4 @@ function SignOut() {
return
Signing out...
}
-export default withApollo(SignOut)
+export default SignOut
diff --git a/examples/api-routes-apollo-server-and-client-auth/pages/signup.js b/examples/api-routes-apollo-server-and-client-auth/pages/signup.js
index 77146b7759ba2..bcbf81f2410c3 100644
--- a/examples/api-routes-apollo-server-and-client-auth/pages/signup.js
+++ b/examples/api-routes-apollo-server-and-client-auth/pages/signup.js
@@ -1,11 +1,9 @@
-import React from 'react'
+import { useState } from 'react'
+import { useRouter } from 'next/router'
import Link from 'next/link'
-import { withApollo } from '../apollo/client'
-import gql from 'graphql-tag'
-import { useMutation } from '@apollo/react-hooks'
-import Field from '../components/field'
+import { gql, useMutation } from '@apollo/client'
import { getErrorMessage } from '../lib/form'
-import { useRouter } from 'next/router'
+import Field from '../components/field'
const SignUpMutation = gql`
mutation SignUpMutation($email: String!, $password: String!) {
@@ -20,7 +18,7 @@ const SignUpMutation = gql`
function SignUp() {
const [signUp] = useMutation(SignUpMutation)
- const [errorMsg, setErrorMsg] = React.useState()
+ const [errorMsg, setErrorMsg] = useState()
const router = useRouter()
async function handleSubmit(event) {
@@ -62,7 +60,7 @@ function SignUp() {
label="Password"
/>
or{' '}
-
+
Sign in
@@ -70,4 +68,4 @@ function SignUp() {
)
}
-export default withApollo(SignUp)
+export default SignUp
diff --git a/examples/api-routes-apollo-server-and-client/.gitignore b/examples/api-routes-apollo-server-and-client/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/.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/api-routes-apollo-server-and-client/README.md b/examples/api-routes-apollo-server-and-client/README.md
index 6135512ca3b46..96c454e0527c6 100644
--- a/examples/api-routes-apollo-server-and-client/README.md
+++ b/examples/api-routes-apollo-server-and-client/README.md
@@ -1,41 +1,29 @@
# Apollo Server and Client Example
-[Apollo](https://www.apollographql.com/client/) is a GraphQL client that allows you to easily query the exact data you need from a GraphQL server. In addition to fetching and mutating data, Apollo analyzes your queries and their results to construct a client-side cache of your data, which is kept up to date as further queries and mutations are run, fetching more results from the server.
+[Apollo](https://www.apollographql.com/client/) is a GraphQL client that allows you to easily query the exact data you need from a GraphQL server. In addition to fetching and mutating data, Apollo analyzes your queries and their results to construct a client-side cache of your data, which is kept up to date as further queries and mutations are run.
-In this simple example, we integrate Apollo seamlessly with Next by wrapping our _pages/\_app.js_ inside a [higher-order component (HOC)](https://facebook.github.io/react/docs/higher-order-components.html). Using the HOC pattern we're able to pass down a central store of query result data created by Apollo into our React component hierarchy defined inside each page of our Next application.
+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.
-On initial page load, while on the server and inside `getInitialProps`, we invoke the Apollo method, [`getDataFromTree`](https://www.apollographql.com/docs/react/api/react-ssr/#getdatafromtree). This method returns a promise; at the point in which the promise resolves, our Apollo Client store is completely initialized.
+## Preview
-Note: Do not be alarmed that you see two renders being executed. Apollo recursively traverses the React render tree looking for Apollo query components. When it has done that, it fetches all these queries and then passes the result to a cache. This cache is then used to render the data on the server side (another React render).
-https://www.apollographql.com/docs/react/api/react-ssr/#getdatafromtree
+Preview the example live on [StackBlitz](http://stackblitz.com/):
-## 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:
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-apollo-server-and-client)
-```bash
-npm init next-app --example api-routes-apollo-server-and-client api-routes-apollo-server-and-client-app
-# or
-yarn create next-app --example api-routes-apollo-server-and-client api-routes-apollo-server-and-client-app
-```
+## Deploy your own
-### Download manually
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-Download the example:
+[](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)
-```bash
-curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/api-routes-apollo-server-and-client
-cd api-routes-apollo-server-and-client
-```
+## How to use
-Install it and run:
+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
-npm install
-npm run dev
+npx create-next-app --example api-routes-apollo-server-and-client api-routes-apollo-server-and-client-app
# or
-yarn
-yarn dev
+yarn create next-app --example api-routes-apollo-server-and-client api-routes-apollo-server-and-client-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)).
diff --git a/examples/api-routes-apollo-server-and-client/apollo/client.js b/examples/api-routes-apollo-server-and-client/apollo/client.js
index d39cf04f042fd..0a709fd8a716c 100644
--- a/examples/api-routes-apollo-server-and-client/apollo/client.js
+++ b/examples/api-routes-apollo-server-and-client/apollo/client.js
@@ -1,148 +1,47 @@
-import React from 'react'
-import Head from 'next/head'
-import { ApolloProvider } from '@apollo/react-hooks'
-import { ApolloClient } from 'apollo-client'
-import { InMemoryCache } from 'apollo-cache-inmemory'
+import { useMemo } from 'react'
+import { ApolloClient, InMemoryCache } from '@apollo/client'
-let globalApolloClient = null
-
-/**
- * Creates and provides the apolloContext
- * to a next.js PageTree. Use it by wrapping
- * your PageComponent via HOC pattern.
- * @param {Function|Class} PageComponent
- * @param {Object} [config]
- * @param {Boolean} [config.ssr=true]
- */
-export function withApollo(PageComponent, { ssr = true } = {}) {
- const WithApollo = ({ apolloClient, apolloState, ...pageProps }) => {
- const client = apolloClient || initApolloClient(apolloState)
- return (
-
-
-
- )
- }
-
- // Set the correct displayName in development
- if (process.env.NODE_ENV !== 'production') {
- const displayName =
- PageComponent.displayName || PageComponent.name || 'Component'
-
- if (displayName === 'App') {
- console.warn('This withApollo HOC only works with PageComponents.')
- }
-
- WithApollo.displayName = `withApollo(${displayName})`
- }
-
- if (ssr || PageComponent.getInitialProps) {
- WithApollo.getInitialProps = async ctx => {
- const { AppTree } = ctx
-
- // Initialize ApolloClient, add it to the ctx object so
- // we can use it in `PageComponent.getInitialProp`.
- const apolloClient = (ctx.apolloClient = initApolloClient())
-
- // Run wrapped getInitialProps methods
- let pageProps = {}
- if (PageComponent.getInitialProps) {
- pageProps = await PageComponent.getInitialProps(ctx)
- }
-
- // Only on the server:
- if (typeof window === 'undefined') {
- // When redirecting, the response is finished.
- // No point in continuing to render
- if (ctx.res && ctx.res.finished) {
- return pageProps
- }
-
- // Only if ssr is enabled
- if (ssr) {
- try {
- // Run all GraphQL queries
- const { getDataFromTree } = await import('@apollo/react-ssr')
- await getDataFromTree(
-
- )
- } catch (error) {
- // Prevent Apollo Client GraphQL errors from crashing SSR.
- // Handle them in components via the data.error prop:
- // https://www.apollographql.com/docs/react/api/react-apollo.html#graphql-query-data-error
- console.error('Error while running `getDataFromTree`', error)
- }
-
- // getDataFromTree does not call componentWillUnmount
- // head side effect therefore need to be cleared manually
- Head.rewind()
- }
- }
-
- // Extract query data from the Apollo store
- const apolloState = apolloClient.cache.extract()
-
- return {
- ...pageProps,
- apolloState,
- }
- }
- }
-
- return WithApollo
-}
-
-/**
- * Always creates a new apollo client on the server
- * Creates or reuses apollo client in the browser.
- * @param {Object} initialState
- */
-function initApolloClient(initialState) {
- // Make sure to create a new client for every server-side request so that data
- // isn't shared between connections (which would be bad)
- if (typeof window === 'undefined') {
- return createApolloClient(initialState)
- }
-
- // Reuse client on the client-side
- if (!globalApolloClient) {
- globalApolloClient = createApolloClient(initialState)
- }
-
- return globalApolloClient
-}
-
-/**
- * Creates and configures the ApolloClient
- * @param {Object} [initialState={}]
- */
-function createApolloClient(initialState = {}) {
- const ssrMode = typeof window === 'undefined'
- const cache = new InMemoryCache().restore(initialState)
-
- // Check out https://github.com/zeit/next.js/pull/4611 if you want to use the AWSAppSyncClient
- return new ApolloClient({
- ssrMode,
- link: createIsomorphLink(),
- cache,
- })
-}
+let apolloClient
function createIsomorphLink() {
if (typeof window === 'undefined') {
- const { SchemaLink } = require('apollo-link-schema')
+ const { SchemaLink } = require('@apollo/client/link/schema')
const { schema } = require('./schema')
return new SchemaLink({ schema })
} else {
- const { HttpLink } = require('apollo-link-http')
+ const { HttpLink } = require('@apollo/client/link/http')
return new HttpLink({
uri: '/api/graphql',
credentials: 'same-origin',
})
}
}
+
+function createApolloClient() {
+ return new ApolloClient({
+ ssrMode: typeof window === 'undefined',
+ link: createIsomorphLink(),
+ cache: new InMemoryCache(),
+ })
+}
+
+export function initializeApollo(initialState = null) {
+ const _apolloClient = apolloClient ?? createApolloClient()
+
+ // If your page has Next.js data fetching methods that use Apollo Client, the initial state
+ // gets hydrated here
+ if (initialState) {
+ _apolloClient.cache.restore(initialState)
+ }
+ // For SSG and SSR always create a new Apollo Client
+ if (typeof window === 'undefined') return _apolloClient
+ // Create the Apollo Client once in the client
+ if (!apolloClient) apolloClient = _apolloClient
+
+ return _apolloClient
+}
+
+export function useApollo(initialState) {
+ const store = useMemo(() => initializeApollo(initialState), [initialState])
+ return store
+}
diff --git a/examples/api-routes-apollo-server-and-client/apollo/type-defs.js b/examples/api-routes-apollo-server-and-client/apollo/type-defs.js
index e6da839c1b650..53c485d64e499 100644
--- a/examples/api-routes-apollo-server-and-client/apollo/type-defs.js
+++ b/examples/api-routes-apollo-server-and-client/apollo/type-defs.js
@@ -1,4 +1,4 @@
-import gql from 'graphql-tag'
+import { gql } from '@apollo/client'
export const typeDefs = gql`
type User {
diff --git a/examples/api-routes-apollo-server-and-client/package.json b/examples/api-routes-apollo-server-and-client/package.json
index cdab52d8526d5..1276194f65bc3 100644
--- a/examples/api-routes-apollo-server-and-client/package.json
+++ b/examples/api-routes-apollo-server-and-client/package.json
@@ -1,28 +1,18 @@
{
- "name": "with-apollo",
- "version": "2.0.0",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start"
},
"dependencies": {
- "@apollo/react-common": "3.0.1",
- "@apollo/react-hooks": "3.0.1",
- "@apollo/react-ssr": "3.0.1",
- "apollo-cache-inmemory": "1.6.3",
- "apollo-client": "2.6.4",
- "apollo-link-http": "1.5.15",
- "apollo-link-schema": "1.2.3",
- "apollo-server-micro": "2.9.0",
- "apollo-utilities": "^1.3.2",
+ "@apollo/client": "^3.0.2",
+ "apollo-server-micro": "^2.14.2",
"graphql": "^14.0.2",
- "graphql-tag": "2.10.1",
"next": "latest",
"prop-types": "^15.6.2",
- "react": "^16.7.0",
- "react-dom": "^16.7.0"
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2"
},
- "author": "",
- "license": "ISC"
+ "license": "MIT"
}
diff --git a/examples/api-routes-apollo-server-and-client/pages/_app.js b/examples/api-routes-apollo-server-and-client/pages/_app.js
new file mode 100644
index 0000000000000..482728ae76e6d
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/pages/_app.js
@@ -0,0 +1,12 @@
+import { ApolloProvider } from '@apollo/client'
+import { useApollo } from '../apollo/client'
+
+export default function App({ Component, pageProps }) {
+ const apolloClient = useApollo(pageProps.initialApolloState)
+
+ return (
+
+
+
+ )
+}
diff --git a/examples/api-routes-apollo-server-and-client/pages/about.js b/examples/api-routes-apollo-server-and-client/pages/about.js
index 37a11a9e09651..4d21f1676c4c2 100644
--- a/examples/api-routes-apollo-server-and-client/pages/about.js
+++ b/examples/api-routes-apollo-server-and-client/pages/about.js
@@ -1,11 +1,13 @@
import Link from 'next/link'
-export default () => (
-
- This is a static page goto{' '}
-
- dynamic
- {' '}
- page.
-
-)
+export default function About() {
+ return (
+
+ This is a static page goto{' '}
+
+ dynamic
+ {' '}
+ page.
+
+ )
+}
diff --git a/examples/api-routes-apollo-server-and-client/pages/index.js b/examples/api-routes-apollo-server-and-client/pages/index.js
index 33ab4252a092d..4c40076bb98bb 100644
--- a/examples/api-routes-apollo-server-and-client/pages/index.js
+++ b/examples/api-routes-apollo-server-and-client/pages/index.js
@@ -1,7 +1,7 @@
-import { withApollo } from '../apollo/client'
import gql from 'graphql-tag'
import Link from 'next/link'
-import { useQuery } from '@apollo/react-hooks'
+import { useQuery } from '@apollo/client'
+import { initializeApollo } from '../apollo/client'
const ViewerQuery = gql`
query ViewerQuery {
@@ -18,19 +18,29 @@ const Index = () => {
data: { viewer },
} = useQuery(ViewerQuery)
- if (viewer) {
- return (
-
- You're signed in as {viewer.name} and you're {viewer.status} goto{' '}
-
- static
- {' '}
- page.
-
- )
- }
+ return (
+
+ You're signed in as {viewer.name} and you're {viewer.status} goto{' '}
+
+ static
+ {' '}
+ page.
+
+ )
+}
+
+export async function getStaticProps() {
+ const apolloClient = initializeApollo()
- return null
+ await apolloClient.query({
+ query: ViewerQuery,
+ })
+
+ return {
+ props: {
+ initialApolloState: apolloClient.cache.extract(),
+ },
+ }
}
-export default withApollo(Index)
+export default Index
diff --git a/examples/api-routes-apollo-server/.gitignore b/examples/api-routes-apollo-server/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ b/examples/api-routes-apollo-server/.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/api-routes-apollo-server/README.md b/examples/api-routes-apollo-server/README.md
new file mode 100644
index 0000000000000..9b4209908adb2
--- /dev/null
+++ b/examples/api-routes-apollo-server/README.md
@@ -0,0 +1,35 @@
+# Consume local Apollo GraphQL schema to create Static Generation export
+
+Next.js ships with two forms of pre-rendering: [Static Generation](https://nextjs.org/docs/basic-features/pages#static-generation-recommended) and [Server-side Rendering](https://nextjs.org/docs/basic-features/pages#server-side-rendering). This example shows how to perform Static Generation using a local [Apollo GraphQL](https://www.apollographql.com/docs/apollo-server/) schema within [getStaticProps](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) and [getStaticPaths](https://nextjs.org/docs/basic-features/data-fetching#getstaticpaths-static-generation). The end result is a Next.js application that uses one Apollo GraphQL schema to generate static pages at build time and also serve a GraphQL [API Route](https://nextjs.org/docs/api-routes/introduction) at runtime.
+
+## Preview
+
+Preview the example live on [StackBlitz](http://stackblitz.com/):
+
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-apollo-server)
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-apollo-server&project-name=api-routes-apollo-server&repository-name=api-routes-apollo-server)
+
+## 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 api-routes-apollo-server api-routes-apollo-server-app
+# or
+yarn create next-app --example api-routes-apollo-server api-routes-apollo-server-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)).
+
+## Notes
+
+### Static Export
+
+If you wish to export a static HTML + JS version of the site you need to first change the setting in this example in `./pages/[username].js` where `getStaticPaths` has `fallback: true` - this needs to be `false` for static export to work. You can then run `npm run build` and `npm run export` to export the site as a static folder in `./out` directory.
+
+[Read more about fallback option](https://nextjs.org/docs/basic-features/data-fetching#the-fallback-key-required)
diff --git a/examples/api-routes-apollo-server/package.json b/examples/api-routes-apollo-server/package.json
new file mode 100644
index 0000000000000..9df4ce239ee3f
--- /dev/null
+++ b/examples/api-routes-apollo-server/package.json
@@ -0,0 +1,17 @@
+{
+ "private": true,
+ "scripts": {
+ "dev": "next",
+ "build": "next build",
+ "export": "next export",
+ "start": "next start"
+ },
+ "dependencies": {
+ "apollo-server-micro": "2.13.1",
+ "graphql": "15.0.0",
+ "next": "latest",
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2"
+ },
+ "license": "MIT"
+}
diff --git a/examples/api-routes-apollo-server/pages/[username].js b/examples/api-routes-apollo-server/pages/[username].js
new file mode 100644
index 0000000000000..30f792c375ae2
--- /dev/null
+++ b/examples/api-routes-apollo-server/pages/[username].js
@@ -0,0 +1,45 @@
+import queryGraphql from '../shared/query-graphql'
+
+export default function UserProfile({ user }) {
+ if (!user) {
+ return
+ )
+}
+
+export async function getStaticProps() {
+ const { users } = await queryGraphql(`
+ query {
+ users {
+ name
+ username
+ }
+ }
+ `)
+ return { props: { users } }
+}
diff --git a/examples/api-routes-apollo-server/shared/query-graphql/index.js b/examples/api-routes-apollo-server/shared/query-graphql/index.js
new file mode 100644
index 0000000000000..9393dbf8f237c
--- /dev/null
+++ b/examples/api-routes-apollo-server/shared/query-graphql/index.js
@@ -0,0 +1,8 @@
+import { graphql } from 'graphql'
+
+import { schema } from '../../pages/api/graphql'
+
+export default async function queryGraphql(query, variableValues = {}) {
+ const { data } = await graphql({ schema, source: query, variableValues })
+ return data || {}
+}
diff --git a/examples/api-routes-cors/.gitignore b/examples/api-routes-cors/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ b/examples/api-routes-cors/.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/api-routes-cors/README.md b/examples/api-routes-cors/README.md
new file mode 100644
index 0000000000000..5ba1b348401fc
--- /dev/null
+++ b/examples/api-routes-cors/README.md
@@ -0,0 +1,29 @@
+# API Routes Example with CORS
+
+Next.js ships with [API routes](https://nextjs.org/docs/api-routes/introduction) which provides an easy solution to build your own `API`.
+
+This example shows how to create an `API` endpoint with [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) headers, using the [cors](https://github.com/expressjs/cors) package.
+
+## Preview
+
+Preview the example live on [StackBlitz](http://stackblitz.com/):
+
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-cors)
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-cors&project-name=api-routes-cors&repository-name=api-routes-cors)
+
+## 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 api-routes-cors api-routes-cors-app
+# or
+yarn create next-app --example api-routes-cors api-routes-cors-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)).
diff --git a/examples/api-routes-cors/lib/init-middleware.js b/examples/api-routes-cors/lib/init-middleware.js
new file mode 100644
index 0000000000000..8af0a8fe7be5b
--- /dev/null
+++ b/examples/api-routes-cors/lib/init-middleware.js
@@ -0,0 +1,13 @@
+// Helper method to wait for a middleware to execute before continuing
+// And to throw an error when an error happens in a middleware
+export default function initMiddleware(middleware) {
+ return (req, res) =>
+ new Promise((resolve, reject) => {
+ middleware(req, res, (result) => {
+ if (result instanceof Error) {
+ return reject(result)
+ }
+ return resolve(result)
+ })
+ })
+}
diff --git a/examples/api-routes-cors/package.json b/examples/api-routes-cors/package.json
new file mode 100644
index 0000000000000..f6e1ae73487a9
--- /dev/null
+++ b/examples/api-routes-cors/package.json
@@ -0,0 +1,15 @@
+{
+ "private": true,
+ "scripts": {
+ "dev": "next",
+ "build": "next build",
+ "start": "next start"
+ },
+ "dependencies": {
+ "cors": "2.8.5",
+ "next": "latest",
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2"
+ },
+ "license": "MIT"
+}
diff --git a/examples/api-routes-cors/pages/api/cors.js b/examples/api-routes-cors/pages/api/cors.js
new file mode 100644
index 0000000000000..8e5fc7d066cb9
--- /dev/null
+++ b/examples/api-routes-cors/pages/api/cors.js
@@ -0,0 +1,19 @@
+import Cors from 'cors'
+import initMiddleware from '../../lib/init-middleware'
+
+// Initialize the cors middleware
+const cors = initMiddleware(
+ // You can read more about the available options here: https://github.com/expressjs/cors#configuration-options
+ Cors({
+ // Only allow requests with GET, POST and OPTIONS
+ methods: ['GET', 'POST', 'OPTIONS'],
+ })
+)
+
+export default async function handler(req, res) {
+ // Run cors
+ await cors(req, res)
+
+ // Rest of the API logic
+ res.json({ message: 'Hello Everyone!' })
+}
diff --git a/examples/api-routes-cors/pages/index.js b/examples/api-routes-cors/pages/index.js
new file mode 100644
index 0000000000000..9506fde9d82f4
--- /dev/null
+++ b/examples/api-routes-cors/pages/index.js
@@ -0,0 +1,9 @@
+export default function Index() {
+ return (
+
+ To test the CORS route, open the console in a new tab on a different
+ domain and make a POST / GET / OPTIONS request to /api/cors. Using
+ a different method from those mentioned will be blocked by CORS
+
+ )
+}
diff --git a/examples/api-routes-graphql/.gitignore b/examples/api-routes-graphql/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ b/examples/api-routes-graphql/.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/api-routes-graphql/README.md b/examples/api-routes-graphql/README.md
index 5c583ba56e65f..1c51cf4d7e38b 100644
--- a/examples/api-routes-graphql/README.md
+++ b/examples/api-routes-graphql/README.md
@@ -1,42 +1,27 @@
# API routes with GraphQL server
-Next.js ships with [API routes](https://github.com/zeit/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows their usage alongside [apollo-server-micro](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-micro) to provide simple GraphQL server consumed by Next.js app.
+Next.js ships with [API routes](https://github.com/vercel/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows their usage alongside [apollo-server-micro](https://github.com/apollographql/apollo-server/tree/main/packages/apollo-server-micro) to provide simple GraphQL server consumed by Next.js app.
-## Deploy your own
-
-Deploy the example using [ZEIT Now](https://zeit.co/now):
+## Preview
-[](https://zeit.co/import/project?template=https://github.com/zeit/next.js/tree/canary/examples/api-routes-graphql)
-
-## How to use
+Preview the example live on [StackBlitz](http://stackblitz.com/):
-### Using `create-next-app`
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-graphql)
-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
-npm init next-app --example api-routes-graphql api-routes-graphql-app
-# or
-yarn create next-app --example api-routes-graphql api-routes-graphql-app
-```
+## Deploy your own
-### Download manually
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-Download the example:
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-graphql&project-name=api-routes-graphql&repository-name=api-routes-graphql)
-```bash
-curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/api-routes-graphql
-cd api-routes-graphql
-```
+## How to use
-Install it and run:
+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
-npm install
-npm run dev
+npx create-next-app --example api-routes-graphql api-routes-graphql-app
# or
-yarn
-yarn dev
+yarn create next-app --example api-routes-graphql api-routes-graphql-app
```
-Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+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)).
diff --git a/examples/api-routes-graphql/package.json b/examples/api-routes-graphql/package.json
index 3002140e0991c..4884a0e6d4038 100644
--- a/examples/api-routes-graphql/package.json
+++ b/examples/api-routes-graphql/package.json
@@ -1,18 +1,18 @@
{
- "name": "api-routes-graphql",
- "version": "1.0.0",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start"
},
"dependencies": {
- "apollo-server-micro": "2.11.0",
- "graphql": "14.6.0",
+ "apollo-server-micro": "^3.0.1",
+ "graphql": "^15.5.1",
+ "micro": "^9.3.4",
"next": "latest",
- "react": "16.13.1",
- "react-dom": "16.13.1",
- "swr": "0.1.18"
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2",
+ "swr": "^0.5.6"
},
- "license": "ISC"
+ "license": "MIT"
}
diff --git a/examples/api-routes-graphql/pages/api/graphql.js b/examples/api-routes-graphql/pages/api/graphql.js
index 0dcb066bbcbdc..0a29f3ce88987 100644
--- a/examples/api-routes-graphql/pages/api/graphql.js
+++ b/examples/api-routes-graphql/pages/api/graphql.js
@@ -19,10 +19,31 @@ const resolvers = {
const apolloServer = new ApolloServer({ typeDefs, resolvers })
+const startServer = apolloServer.start()
+
+export default async function handler(req, res) {
+ res.setHeader('Access-Control-Allow-Credentials', 'true')
+ res.setHeader(
+ 'Access-Control-Allow-Origin',
+ 'https://studio.apollographql.com'
+ )
+ res.setHeader(
+ 'Access-Control-Allow-Headers',
+ 'Origin, X-Requested-With, Content-Type, Accept'
+ )
+ if (req.method === 'OPTIONS') {
+ res.end()
+ return false
+ }
+
+ await startServer
+ await apolloServer.createHandler({
+ path: '/api/graphql',
+ })(req, res)
+}
+
export const config = {
api: {
bodyParser: false,
},
}
-
-export default apolloServer.createHandler({ path: '/api/graphql' })
diff --git a/examples/api-routes-graphql/pages/index.js b/examples/api-routes-graphql/pages/index.js
index e62fb7bc24f36..9a0bbc3b79538 100644
--- a/examples/api-routes-graphql/pages/index.js
+++ b/examples/api-routes-graphql/pages/index.js
@@ -1,6 +1,6 @@
import useSWR from 'swr'
-const fetcher = query =>
+const fetcher = (query) =>
fetch('/api/graphql', {
method: 'POST',
headers: {
@@ -8,8 +8,8 @@ const fetcher = query =>
},
body: JSON.stringify({ query }),
})
- .then(res => res.json())
- .then(json => json.data)
+ .then((res) => res.json())
+ .then((json) => json.data)
export default function Index() {
const { data, error } = useSWR('{ users { name } }', fetcher)
diff --git a/examples/api-routes-middleware/.gitignore b/examples/api-routes-middleware/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ b/examples/api-routes-middleware/.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/api-routes-middleware/README.md b/examples/api-routes-middleware/README.md
index 4e058d564928c..44a12e118ddcb 100644
--- a/examples/api-routes-middleware/README.md
+++ b/examples/api-routes-middleware/README.md
@@ -1,42 +1,27 @@
# API routes with middleware
-Next.js ships with [API routes](https://github.com/zeit/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows how to implement simple `middleware` to wrap around your `API` endpoints.
+Next.js ships with [API routes](https://github.com/vercel/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows how to implement simple `middleware` to wrap around your `API` endpoints.
-## Deploy your own
-
-Deploy the example using [ZEIT Now](https://zeit.co/now):
+## Preview
-[](https://zeit.co/import/project?template=https://github.com/zeit/next.js/tree/canary/examples/api-routes-middleware)
-
-## How to use
+Preview the example live on [StackBlitz](http://stackblitz.com/):
-### Using `create-next-app`
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-middleware)
-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
-npm init next-app --example api-routes-middleware api-routes-middleware-app
-# or
-yarn create next-app --example api-routes-middleware api-routes-middleware-app
-```
+## Deploy your own
-### Download manually
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-Download the example:
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-middleware&project-name=api-routes-middleware&repository-name=api-routes-middleware)
-```bash
-curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/api-routes-middleware
-cd api-routes-middleware
-```
+## How to use
-Install it and run:
+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
-npm install
-npm run dev
+npx create-next-app --example api-routes-middleware api-routes-middleware-app
# or
-yarn
-yarn dev
+yarn create next-app --example api-routes-middleware api-routes-middleware-app
```
-Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+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)).
diff --git a/examples/api-routes-middleware/package.json b/examples/api-routes-middleware/package.json
index 747c705b41a1f..c68633f692ff3 100644
--- a/examples/api-routes-middleware/package.json
+++ b/examples/api-routes-middleware/package.json
@@ -1,6 +1,5 @@
{
- "name": "api-routes-middleware",
- "version": "1.0.0",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build",
@@ -9,9 +8,9 @@
"dependencies": {
"cookie": "0.4.0",
"next": "latest",
- "react": "^16.8.6",
- "react-dom": "^16.8.6",
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2",
"swr": "0.1.18"
},
- "license": "ISC"
+ "license": "MIT"
}
diff --git a/examples/api-routes-middleware/pages/index.js b/examples/api-routes-middleware/pages/index.js
index 9f745a01987c9..51c784cc104a7 100644
--- a/examples/api-routes-middleware/pages/index.js
+++ b/examples/api-routes-middleware/pages/index.js
@@ -1,6 +1,6 @@
import useSWR from 'swr'
-const fetcher = url => fetch(url).then(res => res.text())
+const fetcher = (url) => fetch(url).then((res) => res.text())
export default function Index() {
const { data, error } = useSWR('/api/cookies', fetcher)
diff --git a/examples/api-routes-middleware/utils/cookies.js b/examples/api-routes-middleware/utils/cookies.js
index 6409c7361726e..9e48b0405d7b8 100644
--- a/examples/api-routes-middleware/utils/cookies.js
+++ b/examples/api-routes-middleware/utils/cookies.js
@@ -18,7 +18,7 @@ const cookie = (res, name, value, options = {}) => {
/**
* Adds `cookie` function on `res.cookie` to set cookies for response
*/
-const cookies = handler => (req, res) => {
+const cookies = (handler) => (req, res) => {
res.cookie = (name, value, options) => cookie(res, name, value, options)
return handler(req, res)
diff --git a/examples/api-routes-rate-limit/.gitignore b/examples/api-routes-rate-limit/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ b/examples/api-routes-rate-limit/.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/api-routes-rate-limit/README.md b/examples/api-routes-rate-limit/README.md
new file mode 100644
index 0000000000000..9328d25846365
--- /dev/null
+++ b/examples/api-routes-rate-limit/README.md
@@ -0,0 +1,41 @@
+# API Routes Rate Limiting Example
+
+This example uses `lru-cache` to implement a simple rate limiter for API routes ([Serverless Functions](https://vercel.com/docs/serverless-functions/introduction)).
+
+**Demo: https://nextjs-rate-limit.vercel.app/**
+
+```bash
+curl http://localhost:3000/api/user -I
+HTTP/1.1 200 OK
+X-RateLimit-Limit: 10
+X-RateLimit-Remaining: 9
+
+curl http://localhost:3000/api/user -I
+HTTP/1.1 429 Too Many Requests
+X-RateLimit-Limit: 10
+X-RateLimit-Remaining: 0
+```
+
+## Preview
+
+Preview the example live on [StackBlitz](http://stackblitz.com/):
+
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-rate-limit)
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-rate-limit&project-name=api-routes-rate-limit&repository-name=api-routes-rate-limit)
+
+## 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 api-routes-rate-limit api-routes-rate-limit-app
+# or
+yarn create next-app --example api-routes-rate-limit api-routes-rate-limit-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)).
diff --git a/examples/api-routes-rate-limit/package.json b/examples/api-routes-rate-limit/package.json
new file mode 100644
index 0000000000000..568cc38e0b848
--- /dev/null
+++ b/examples/api-routes-rate-limit/package.json
@@ -0,0 +1,15 @@
+{
+ "private": true,
+ "scripts": {
+ "dev": "next dev",
+ "build": "next build",
+ "start": "next start"
+ },
+ "dependencies": {
+ "lru-cache": "^6.0.0",
+ "next": "10.0.3",
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2",
+ "uuid": "^8.3.1"
+ }
+}
diff --git a/examples/api-routes-rate-limit/pages/api/user.js b/examples/api-routes-rate-limit/pages/api/user.js
new file mode 100644
index 0000000000000..2380dad3577f3
--- /dev/null
+++ b/examples/api-routes-rate-limit/pages/api/user.js
@@ -0,0 +1,16 @@
+import * as uuid from 'uuid'
+import rateLimit from '../../utils/rate-limit'
+
+const limiter = rateLimit({
+ interval: 60 * 1000, // 60 seconds
+ uniqueTokenPerInterval: 500, // Max 500 users per second
+})
+
+export default async function handler(req, res) {
+ try {
+ await limiter.check(res, 10, 'CACHE_TOKEN') // 10 requests per minute
+ res.status(200).json({ id: uuid.v4() })
+ } catch {
+ res.status(429).json({ error: 'Rate limit exceeded' })
+ }
+}
diff --git a/examples/api-routes-rate-limit/pages/index.js b/examples/api-routes-rate-limit/pages/index.js
new file mode 100644
index 0000000000000..3c5cfc8564998
--- /dev/null
+++ b/examples/api-routes-rate-limit/pages/index.js
@@ -0,0 +1,52 @@
+import { useState } from 'react'
+import styles from '../styles.module.css'
+
+export default function Index() {
+ const [response, setResponse] = useState()
+
+ const makeRequest = async () => {
+ const res = await fetch('/api/user')
+
+ setResponse({
+ status: res.status,
+ body: await res.json(),
+ limit: res.headers.get('X-RateLimit-Limit'),
+ remaining: res.headers.get('X-RateLimit-Remaining'),
+ })
+ }
+
+ return (
+
+
Next.js API Routes Rate Limiting
+
+ This example uses lru-cache{' '}
+ to implement a simple rate limiter for API routes (Serverless
+ Functions).
+
diff --git a/examples/api-routes/.gitignore b/examples/api-routes/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ b/examples/api-routes/.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/api-routes/README.md b/examples/api-routes/README.md
index a3e39812d797e..87e9fa6321f9d 100644
--- a/examples/api-routes/README.md
+++ b/examples/api-routes/README.md
@@ -2,41 +2,26 @@
Next.js ships with [API routes](https://nextjs.org/docs/api-routes/introduction) which provides an easy solution to build your own `API`. This example shows how to create multiple `API` endpoints with serverless functions, which can execute independently.
-## Deploy your own
-
-Deploy the example using [ZEIT Now](https://zeit.co/now):
+## Preview
-[](https://zeit.co/import/project?template=https://github.com/zeit/next.js/tree/canary/examples/api-routes)
-
-## How to use
+Preview the example live on [StackBlitz](http://stackblitz.com/):
-### Using `create-next-app`
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes)
-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
-npm init next-app --example api-routes api-routes-app
-# or
-yarn create next-app --example api-routes api-routes-app
-```
+## Deploy your own
-### Download manually
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-Download the example:
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes&project-name=api-routes&repository-name=api-routes)
-```bash
-curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/api-routes
-cd api-routes
-```
+## How to use
-Install it and run:
+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
-npm install
-npm run dev
+npx create-next-app --example api-routes api-routes-app
# or
-yarn
-yarn dev
+yarn create next-app --example api-routes api-routes-app
```
-Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+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)).
diff --git a/examples/api-routes/components/Person.js b/examples/api-routes/components/Person.js
index d43584b1668bc..a53dc51a2b463 100644
--- a/examples/api-routes/components/Person.js
+++ b/examples/api-routes/components/Person.js
@@ -1,9 +1,11 @@
import Link from 'next/link'
-export default ({ person }) => (
-
+ )
+}
diff --git a/examples/api-routes/package.json b/examples/api-routes/package.json
index b45f65e65a6e3..1d9bf5a9c4ea6 100644
--- a/examples/api-routes/package.json
+++ b/examples/api-routes/package.json
@@ -1,6 +1,5 @@
{
- "name": "api-routes",
- "version": "1.0.0",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build",
@@ -8,9 +7,9 @@
},
"dependencies": {
"next": "latest",
- "react": "^16.8.6",
- "react-dom": "^16.8.6",
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2",
"swr": "0.1.18"
},
- "license": "ISC"
+ "license": "MIT"
}
diff --git a/examples/api-routes/pages/api/people/[id].js b/examples/api-routes/pages/api/people/[id].js
index a118dc41a431b..7620901340875 100644
--- a/examples/api-routes/pages/api/people/[id].js
+++ b/examples/api-routes/pages/api/people/[id].js
@@ -1,7 +1,7 @@
import { people } from '../../../data'
-export default ({ query: { id } }, res) => {
- const filtered = people.filter(p => p.id === id)
+export default function personHandler({ query: { id } }, res) {
+ const filtered = people.filter((p) => p.id === id)
// User with id exists
if (filtered.length > 0) {
diff --git a/examples/api-routes/pages/api/people/index.js b/examples/api-routes/pages/api/people/index.js
index a5651c23cd0a8..0c56720da834e 100644
--- a/examples/api-routes/pages/api/people/index.js
+++ b/examples/api-routes/pages/api/people/index.js
@@ -1,5 +1,5 @@
import { people } from '../../../data'
-export default (req, res) => {
+export default function handler(req, res) {
res.status(200).json(people)
}
diff --git a/examples/api-routes/pages/index.js b/examples/api-routes/pages/index.js
index c619a471c7240..2043d223ae676 100644
--- a/examples/api-routes/pages/index.js
+++ b/examples/api-routes/pages/index.js
@@ -1,7 +1,7 @@
import useSWR from 'swr'
import Person from '../components/Person'
-const fetcher = url => fetch(url).then(res => res.json())
+const fetcher = (url) => fetch(url).then((res) => res.json())
export default function Index() {
const { data, error } = useSWR('/api/people', fetcher)
diff --git a/examples/api-routes/pages/person/[id].js b/examples/api-routes/pages/person/[id].js
index 7e9add5e61e83..0ff5e77edfa64 100644
--- a/examples/api-routes/pages/person/[id].js
+++ b/examples/api-routes/pages/person/[id].js
@@ -1,7 +1,7 @@
import { useRouter } from 'next/router'
import useSWR from 'swr'
-const fetcher = async url => {
+const fetcher = async (url) => {
const res = await fetch(url)
const data = await res.json()
diff --git a/examples/auth0/.env.local.example b/examples/auth0/.env.local.example
new file mode 100644
index 0000000000000..40f6027fa2d3d
--- /dev/null
+++ b/examples/auth0/.env.local.example
@@ -0,0 +1,12 @@
+# Public Environment variables that can be used in the browser.
+NEXT_PUBLIC_AUTH0_CLIENT_ID=
+NEXT_PUBLIC_AUTH0_SCOPE="openid profile"
+NEXT_PUBLIC_AUTH0_DOMAIN=
+NEXT_PUBLIC_BASE_URL="http://localhost:3000"
+NEXT_PUBLIC_REDIRECT_URI="/api/callback"
+NEXT_PUBLIC_POST_LOGOUT_REDIRECT_URI="/"
+
+# Secret environment variables only available to Node.js
+AUTH0_CLIENT_SECRET=
+SESSION_COOKIE_SECRET=
+SESSION_COOKIE_LIFETIME=7200
diff --git a/examples/auth0/.env.template b/examples/auth0/.env.template
deleted file mode 100644
index 52f96ccb544fb..0000000000000
--- a/examples/auth0/.env.template
+++ /dev/null
@@ -1,6 +0,0 @@
-AUTH0_CLIENT_ID=
-AUTH0_DOMAIN=
-AUTH0_CLIENT_SECRET=
-REDIRECT_URI=
-POST_LOGOUT_REDIRECT_URI=
-SESSION_COOKIE_SECRET=
diff --git a/examples/auth0/.gitignore b/examples/auth0/.gitignore
index 120b715f54779..1437c53f70bc2 100644
--- a/examples/auth0/.gitignore
+++ b/examples/auth0/.gitignore
@@ -1,3 +1,34 @@
-node_modules
-.env
-.next
\ No newline at end of file
+# 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/auth0/README.md b/examples/auth0/README.md
index ef4dfe8be1c38..e2b2d97bb4381 100644
--- a/examples/auth0/README.md
+++ b/examples/auth0/README.md
@@ -1,17 +1,24 @@
# Next.js and Auth0 Example
-This example shows how you can use `@auth0/nextjs-auth` to easily add authentication support to your Next.js application.
+This example shows how you can use `@auth0/nextjs-auth` to easily add authentication support to your Next.js application. It tries to cover a few topics:
+
+- Signing in
+- Signing out
+- Loading the user on the server side and adding it as part of SSR ([`pages/advanced/ssr-profile.js`](pages/advanced/ssr-profile.js))
+- Loading the user on the client side and using fast/cached SSR pages ([`pages/index.js`](pages/index.js))
+- API Routes which can load the current user ([`pages/api/me.js`](pages/api/me.js))
+- Using hooks to make the user available throughout the application ([`lib/user.js`](lib/user.js))
Read more: [https://auth0.com/blog/ultimate-guide-nextjs-authentication-auth0/](https://auth0.com/blog/ultimate-guide-nextjs-authentication-auth0/)
-### Using `create-next-app`
+## How to use
-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:
+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
-npm init next-app --example auth0 auth0
+npx create-next-app --example auth0 auth0-app
# or
-yarn create next-app --example auth0 auth0
+yarn create next-app --example auth0 auth0-app
```
## Configuring Auth0
@@ -25,76 +32,33 @@ yarn create next-app --example auth0 auth0
4. Save the settings
-### Configuring Next.js
-
-In the Next.js configuration file (`next.config.js`) you'll see that different environment variables are being assigned.
-
-### Local Development
+### Set up environment variables
-For local development you'll want to create a `.env` file with the necessary settings.
+To connect the app with Auth0, you'll need to add the settings from your Auth0 application as environment variables
-The required settings can be found on the Auth0 application's settings page:
+Copy the `.env.local.example` file in this directory to `.env.local` (which will be ignored by Git):
-```
-AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
-AUTH0_CLIENT_ID=YOUR_AUTH0_CLIENT_ID
-AUTH0_CLIENT_SECRET=YOUR_AUTH0_CLIENT_SECRET
-
-SESSION_COOKIE_SECRET=viloxyf_z2GW6K4CT-KQD_MoLEA2wqv5jWuq4Jd0P7ymgG5GJGMpvMneXZzhK3sL (at least 32 characters, used to encrypt the cookie)
-
-REDIRECT_URI=http://localhost:3000/api/callback
-POST_LOGOUT_REDIRECT_URI=http://localhost:3000/
+```bash
+cp .env.local.example .env.local
```
-### Hosting on ZEIT Now
-
-When deploying this example to ZEIT Now you'll want to update the `now.json` configuration file.
-
-```json
-{
- "build": {
- "env": {
- "AUTH0_DOMAIN": "YOUR_AUTH0_DOMAIN",
- "AUTH0_CLIENT_ID": "YOUR_AUTH0_CLIENT_ID",
- "AUTH0_CLIENT_SECRET": "@auth0_client_secret",
- "REDIRECT_URI": "https://my-website.now.sh/api/callback",
- "POST_LOGOUT_REDIRECT_URI": "https://my-website.now.sh/",
- "SESSION_COOKIE_SECRET": "@session_cookie_secret",
- "SESSION_COOKIE_LIFETIME": 7200
- }
- }
-}
-```
+Then, open `.env.local` and add the missing environment variables:
-- `AUTH0_DOMAIN` - Can be found in the Auth0 dashboard under `settings`.
-- `AUTH0_CLIENT_ID` - Can be found in the Auth0 dashboard under `settings`.
+- `NEXT_PUBLIC_AUTH0_DOMAIN` - Can be found in the Auth0 dashboard under `settings`. (Should be prefixed with `https://`)
+- `NEXT_PUBLIC_AUTH0_CLIENT_ID` - Can be found in the Auth0 dashboard under `settings`.
- `AUTH0_CLIENT_SECRET` - Can be found in the Auth0 dashboard under `settings`.
-- `REDIRECT_URI` - The url where Auth0 redirects back to, make sure a consistent url is used here.
-- `POST_LOGOUT_REDIRECT_URI` - Where to redirect after logging out
-- `SESSION_COOKIE_SECRET` - A unique secret used to encrypt the cookies, has to be at least 32 characters. You can use [this generator](https://generate-secret.now.sh/32) to generate a value.
+- `NEXT_PUBLIC_BASE_URL` - The base url of the application.
+- `NEXT_PUBLIC_REDIRECT_URI` - The relative url path where Auth0 redirects back to.
+- `NEXT_PUBLIC_POST_LOGOUT_REDIRECT_URI` - Where to redirect after logging out.
+- `SESSION_COOKIE_SECRET` - A unique secret used to encrypt the cookies, has to be at least 32 characters. You can use [this generator](https://generate-secret.vercel.app/32) to generate a value.
- `SESSION_COOKIE_LIFETIME` - How long a session lasts in seconds. The default is 2 hours.
-The `@auth0_client_secret` and `@session_cookie_secret` are [ZEIT Now environment secrets](https://zeit.co/docs/v2/environment-variables-and-secrets/)
+## Deploy on Vercel
-You can create the `@auth0_client_secret` by running:
+You can deploy this app to the cloud with [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
-```
-now secrets add auth0_client_secret PLACE_YOUR_AUTH0_CLIENT_SECRET
-```
-
-And create the `session_cookie_secret` by generating a value [here](https://generate-secret.now.sh/32) and running:
+### Deploy Your Local Project
-```
-now secrets add session_cookie_secret PLACE_YOUR_SESSION_COOKIE_SECRET
-```
+To deploy your local project to Vercel, push it to GitHub/GitLab/Bitbucket and [import to Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example).
-## About this sample
-
-This sample tries to cover a few topics:
-
-- Signing in
-- Signing out
-- Loading the user on the server side and adding it as part of SSR (`/pages/advanced/ssr-profile.js`)
-- Loading the user on the client side and using fast/cached SSR pages (`/pages/index.js`)
-- API Routes which can load the current user (`/pages/api/me.js`)
-- Using hooks to make the user available throughout the application (`/lib/user.js`)
+**Important**: When you import your project on Vercel, make sure to click on **Environment Variables** and set them to match your `.env.local` file.
diff --git a/examples/auth0/lib/auth0.js b/examples/auth0/lib/auth0.js
index c233f803de179..ffcf3450c5890 100644
--- a/examples/auth0/lib/auth0.js
+++ b/examples/auth0/lib/auth0.js
@@ -1,15 +1,24 @@
import { initAuth0 } from '@auth0/nextjs-auth0'
-import config from './config'
export default initAuth0({
- clientId: config.AUTH0_CLIENT_ID,
- clientSecret: config.AUTH0_CLIENT_SECRET,
- scope: config.AUTH0_SCOPE,
- domain: config.AUTH0_DOMAIN,
- redirectUri: config.REDIRECT_URI,
- postLogoutRedirectUri: config.POST_LOGOUT_REDIRECT_URI,
+ secret: process.env.SESSION_COOKIE_SECRET,
+ issuerBaseURL: process.env.NEXT_PUBLIC_AUTH0_DOMAIN,
+ baseURL: process.env.NEXT_PUBLIC_BASE_URL,
+ clientID: process.env.NEXT_PUBLIC_AUTH0_CLIENT_ID,
+ clientSecret: process.env.AUTH0_CLIENT_SECRET,
+ routes: {
+ callback:
+ process.env.NEXT_PUBLIC_REDIRECT_URI ||
+ 'http://localhost:3000/api/callback',
+ postLogoutRedirect:
+ process.env.NEXT_PUBLIC_POST_LOGOUT_REDIRECT_URI ||
+ 'http://localhost:3000',
+ },
+ authorizationParams: {
+ response_type: 'code',
+ scope: process.env.NEXT_PUBLIC_AUTH0_SCOPE,
+ },
session: {
- cookieSecret: config.SESSION_COOKIE_SECRET,
- cookieLifetime: config.SESSION_COOKIE_LIFETIME,
+ absoluteDuration: process.env.SESSION_COOKIE_LIFETIME,
},
})
diff --git a/examples/auth0/lib/config.js b/examples/auth0/lib/config.js
deleted file mode 100644
index b7052748b1928..0000000000000
--- a/examples/auth0/lib/config.js
+++ /dev/null
@@ -1,26 +0,0 @@
-if (typeof window === 'undefined') {
- /**
- * Settings exposed to the server.
- */
- module.exports = {
- AUTH0_CLIENT_ID: process.env.AUTH0_CLIENT_ID,
- AUTH0_CLIENT_SECRET: process.env.AUTH0_CLIENT_SECRET,
- AUTH0_SCOPE: process.env.AUTH0_SCOPE,
- AUTH0_DOMAIN: process.env.AUTH0_DOMAIN,
- REDIRECT_URI: process.env.REDIRECT_URI,
- POST_LOGOUT_REDIRECT_URI: process.env.POST_LOGOUT_REDIRECT_URI,
- SESSION_COOKIE_SECRET: process.env.SESSION_COOKIE_SECRET,
- SESSION_COOKIE_LIFETIME: process.env.SESSION_COOKIE_LIFETIME,
- }
-} else {
- /**
- * Settings exposed to the client.
- */
- module.exports = {
- AUTH0_CLIENT_ID: process.env.AUTH0_CLIENT_ID,
- AUTH0_SCOPE: process.env.AUTH0_SCOPE,
- AUTH0_DOMAIN: process.env.AUTH0_DOMAIN,
- REDIRECT_URI: process.env.REDIRECT_URI,
- POST_LOGOUT_REDIRECT_URI: process.env.POST_LOGOUT_REDIRECT_URI,
- }
-}
diff --git a/examples/auth0/lib/user.js b/examples/auth0/lib/user.js
index 293c04587cd79..8ff0e586100c1 100644
--- a/examples/auth0/lib/user.js
+++ b/examples/auth0/lib/user.js
@@ -1,5 +1,4 @@
import { useState, useEffect } from 'react'
-import fetch from 'isomorphic-unfetch'
export async function fetchUser(cookie = '') {
if (typeof window !== 'undefined' && window.__user) {
@@ -49,7 +48,7 @@ export function useFetchUser({ required } = {}) {
setLoading(true)
let isMounted = true
- fetchUser().then(user => {
+ fetchUser().then((user) => {
// Only set the user if the component is still mounted
if (isMounted) {
// When the user is not logged in but login is required
diff --git a/examples/auth0/next.config.js b/examples/auth0/next.config.js
deleted file mode 100644
index 4b804fdd389ff..0000000000000
--- a/examples/auth0/next.config.js
+++ /dev/null
@@ -1,17 +0,0 @@
-const dotenv = require('dotenv')
-dotenv.config()
-
-module.exports = {
- env: {
- AUTH0_DOMAIN: process.env.AUTH0_DOMAIN,
- AUTH0_CLIENT_ID: process.env.AUTH0_CLIENT_ID,
- AUTH0_CLIENT_SECRET: process.env.AUTH0_CLIENT_SECRET,
- AUTH0_SCOPE: 'openid profile',
- REDIRECT_URI:
- process.env.REDIRECT_URI || 'http://localhost:3000/api/callback',
- POST_LOGOUT_REDIRECT_URI:
- process.env.POST_LOGOUT_REDIRECT_URI || 'http://localhost:3000/',
- SESSION_COOKIE_SECRET: process.env.SESSION_COOKIE_SECRET,
- SESSION_COOKIE_LIFETIME: 7200, // 2 hours
- },
-}
diff --git a/examples/auth0/now.json b/examples/auth0/now.json
deleted file mode 100644
index 7337cfc1c3e79..0000000000000
--- a/examples/auth0/now.json
+++ /dev/null
@@ -1,12 +0,0 @@
-{
- "build": {
- "env": {
- "AUTH0_DOMAIN": "YOUR_AUTH0_DOMAIN",
- "AUTH0_CLIENT_ID": "YOUR_AUTH0_CLIENT_ID",
- "AUTH0_CLIENT_SECRET": "@auth0_client_secret",
- "REDIRECT_URI": "https://my-website.now.sh/api/callback",
- "POST_LOGOUT_REDIRECT_URI": "https://my-website.now.sh/",
- "SESSION_COOKIE_SECRET": "@session_cookie_secret"
- }
- }
-}
diff --git a/examples/auth0/package.json b/examples/auth0/package.json
index 9f3c8afd7941c..96caf0e6d5c95 100644
--- a/examples/auth0/package.json
+++ b/examples/auth0/package.json
@@ -1,18 +1,15 @@
{
- "name": "nextjs-auth0-example",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start"
},
- "author": "",
- "license": "MIT",
"dependencies": {
- "@auth0/nextjs-auth0": "^0.6.0",
- "dotenv": "^8.2.0",
- "isomorphic-unfetch": "^3.0.0",
+ "@auth0/nextjs-auth0": "^1.4.2",
"next": "latest",
- "react": "^16.12.0",
- "react-dom": "^16.12.0"
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2",
+ "tslib": "^2.2.0"
}
}
diff --git a/examples/auth0/pages/about.js b/examples/auth0/pages/about.js
index e8d6e1aa13112..7956f210b0ad9 100644
--- a/examples/auth0/pages/about.js
+++ b/examples/auth0/pages/about.js
@@ -1,5 +1,3 @@
-import React from 'react'
-
import Layout from '../components/layout'
import { useFetchUser } from '../lib/user'
diff --git a/examples/auth0/pages/advanced/ssr-profile.js b/examples/auth0/pages/advanced/ssr-profile.js
index 0bfccaf56881c..84d96d4dbee4c 100644
--- a/examples/auth0/pages/advanced/ssr-profile.js
+++ b/examples/auth0/pages/advanced/ssr-profile.js
@@ -21,9 +21,9 @@ export async function getServerSideProps({ req, res }) {
// Here you can check authentication status directly before rendering the page,
// however the page would be a serverless function, which is more expensive and
// slower than a static page with client side authentication
- const { user } = await auth0.getSession(req)
+ const session = await auth0.getSession(req)
- if (!user) {
+ if (!session || !session.user) {
res.writeHead(302, {
Location: '/api/login',
})
@@ -31,7 +31,7 @@ export async function getServerSideProps({ req, res }) {
return
}
- return { props: { user } }
+ return { props: { user: session.user } }
}
export default Profile
diff --git a/examples/auth0/pages/index.js b/examples/auth0/pages/index.js
index e16a531abdac8..8459dab6e8e5f 100644
--- a/examples/auth0/pages/index.js
+++ b/examples/auth0/pages/index.js
@@ -1,5 +1,3 @@
-import React from 'react'
-
import Layout from '../components/layout'
import { useFetchUser } from '../lib/user'
diff --git a/examples/auth0/pages/profile.js b/examples/auth0/pages/profile.js
index c059c85daa093..a2780c2584d99 100644
--- a/examples/auth0/pages/profile.js
+++ b/examples/auth0/pages/profile.js
@@ -1,5 +1,3 @@
-import React from 'react'
-
// This import is only needed when checking authentication status directly from getInitialProps
// import auth0 from '../lib/auth0'
import { useFetchUser } from '../lib/user'
diff --git a/examples/basic-css/.gitignore b/examples/basic-css/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ b/examples/basic-css/.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/basic-css/README.md b/examples/basic-css/README.md
index aee21396b0255..0f6d8517a7b75 100644
--- a/examples/basic-css/README.md
+++ b/examples/basic-css/README.md
@@ -1,44 +1,27 @@
# Basic CSS example
-Next.js ships with [styled-jsx](https://github.com/zeit/styled-jsx) allowing you to write scope styled components with full css support. This is important for the modularity and code size of your bundles and also for the learning curve of the framework. If you know css you can write styled-jsx right away.
+Next.js has built-in support for [CSS Modules](https://nextjs.org/docs/basic-features/built-in-css-support#adding-component-level-css) allowing you to write scoped CSS by automatically creating a unique class name. CSS Module files can be imported anywhere in your application and you don't have to worry about collisions.
-## Deploy your own
-
-Deploy the example using [ZEIT Now](https://zeit.co/now):
-
-[](https://zeit.co/import/project?template=https://github.com/zeit/next.js/tree/canary/examples/basic-css)
-
-## How to use
-
-[Try it on CodeSandbox](https://codesandbox.io/s/github/zeit/next.js/tree/canary/examples/basic-css)
+## Preview
-### Using `create-next-app`
+Preview the example live on [StackBlitz](http://stackblitz.com/):
-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:
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/basic-css)
-```bash
-npm init next-app --example basic-css basic-css-app
-# or
-yarn create next-app --example basic-css basic-css-app
-```
+## Deploy your own
-### Download manually
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-Download the example:
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/basic-css&project-name=basic-css&repository-name=basic-css)
-```bash
-curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/basic-css
-cd basic-css
-```
+## How to use
-Install it and run:
+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
-npm install
-npm run dev
+npx create-next-app --example basic-css basic-css-app
# or
-yarn
-yarn dev
+yarn create next-app --example basic-css basic-css-app
```
-Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+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)).
diff --git a/examples/basic-css/package.json b/examples/basic-css/package.json
index 3334fd60affff..4f6934191388f 100644
--- a/examples/basic-css/package.json
+++ b/examples/basic-css/package.json
@@ -1,6 +1,5 @@
{
- "name": "basic-css",
- "version": "1.0.0",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build",
@@ -8,8 +7,8 @@
},
"dependencies": {
"next": "latest",
- "react": "^16.7.0",
- "react-dom": "^16.7.0"
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2"
},
- "license": "ISC"
+ "license": "MIT"
}
diff --git a/examples/basic-css/pages/index.js b/examples/basic-css/pages/index.js
index f7764277e13fb..9901f81b33029 100644
--- a/examples/basic-css/pages/index.js
+++ b/examples/basic-css/pages/index.js
@@ -1,17 +1,9 @@
-export default () => (
-
-
Hello World
-
-
-)
+import styles from '../styles.module.css'
+
+export default function Home() {
+ return (
+
+
Hello World
+
+ )
+}
diff --git a/examples/basic-css/styles.module.css b/examples/basic-css/styles.module.css
new file mode 100644
index 0000000000000..b841ef4cfaddb
--- /dev/null
+++ b/examples/basic-css/styles.module.css
@@ -0,0 +1,10 @@
+.hello {
+ font: 15px Helvetica, Arial, sans-serif;
+ background: #eee;
+ padding: 100px;
+ text-align: center;
+ transition: 100ms ease-in background;
+}
+.hello:hover {
+ background: #ccc;
+}
diff --git a/examples/basic-export/.gitignore b/examples/basic-export/.gitignore
index 1fcb1529f8e5e..1437c53f70bc2 100644
--- a/examples/basic-export/.gitignore
+++ b/examples/basic-export/.gitignore
@@ -1 +1,34 @@
-out
+# 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/basic-export/README.md b/examples/basic-export/README.md
index 844040d3d0af4..e53128be24960 100644
--- a/examples/basic-export/README.md
+++ b/examples/basic-export/README.md
@@ -2,41 +2,26 @@
This example shows the most basic usage of `next export`. Without `exportPathMap`.
-## Deploy your own
-
-Deploy the example using [ZEIT Now](https://zeit.co/now):
+## Preview
-[](https://zeit.co/import/project?template=https://github.com/zeit/next.js/tree/canary/examples/basic-export)
-
-## How to use
+Preview the example live on [StackBlitz](http://stackblitz.com/):
-### Using `create-next-app`
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/basic-export)
-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
-npm init next-app --example basic-export basic-export-app
-# or
-yarn create next-app --example basic-export basic-export-app
-```
+## Deploy your own
-### Download manually
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-Download the example:
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/basic-export&project-name=basic-export&repository-name=basic-export)
-```bash
-curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/basic-export
-cd basic-export
-```
+## How to use
-Install it and run:
+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
-npm install
-npm run dev
+npx create-next-app --example basic-export basic-export-app
# or
-yarn
-yarn dev
+yarn create next-app --example basic-export basic-export-app
```
-Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+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)).
diff --git a/examples/basic-export/package.json b/examples/basic-export/package.json
index 031909300b136..8bc9642671268 100644
--- a/examples/basic-export/package.json
+++ b/examples/basic-export/package.json
@@ -1,6 +1,5 @@
{
- "name": "hello-world",
- "version": "1.0.0",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build && next export",
@@ -8,8 +7,8 @@
},
"dependencies": {
"next": "latest",
- "react": "^16.7.0",
- "react-dom": "^16.7.0"
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2"
},
- "license": "ISC"
+ "license": "MIT"
}
diff --git a/examples/basic-export/pages/about.js b/examples/basic-export/pages/about.js
index 5fd65c2baf2cb..46817af02a5c1 100644
--- a/examples/basic-export/pages/about.js
+++ b/examples/basic-export/pages/about.js
@@ -1 +1,3 @@
-export default () =>
+ )
+}
diff --git a/examples/blog-starter-typescript/.gitignore b/examples/blog-starter-typescript/.gitignore
new file mode 100644
index 0000000000000..1437c53f70bc2
--- /dev/null
+++ b/examples/blog-starter-typescript/.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/blog-starter-typescript/@types/remark-html.d.ts b/examples/blog-starter-typescript/@types/remark-html.d.ts
new file mode 100644
index 0000000000000..e1b76b54f7e1e
--- /dev/null
+++ b/examples/blog-starter-typescript/@types/remark-html.d.ts
@@ -0,0 +1 @@
+declare module 'remark-html'
diff --git a/examples/blog-starter-typescript/README.md b/examples/blog-starter-typescript/README.md
new file mode 100644
index 0000000000000..b74a6e5ad721a
--- /dev/null
+++ b/examples/blog-starter-typescript/README.md
@@ -0,0 +1,41 @@
+# A statically generated blog example using Next.js, Markdown, and TypeScript
+
+This is the existing [blog-starter](https://github.com/vercel/next.js/tree/canary/examples/blog-starter) plus TypeScript.
+
+This example showcases Next.js's [Static Generation](https://nextjs.org/docs/basic-features/pages) feature using Markdown files as the data source.
+
+The blog posts are stored in `/_posts` as Markdown files with front matter support. Adding a new Markdown file in there will create a new blog post.
+
+To create the blog posts we use [`remark`](https://github.com/remarkjs/remark) and [`remark-html`](https://github.com/remarkjs/remark-html) to convert the Markdown files into an HTML string, and then send it down as a prop to the page. The metadata of every post is handled by [`gray-matter`](https://github.com/jonschlinkert/gray-matter) and also sent in props to the page.
+
+## Preview
+
+Preview the example live on [StackBlitz](http://stackblitz.com/):
+
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/blog-starter-typescript)
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/blog-starter-typescript&project-name=blog-starter-typescript&repository-name=blog-starter-typescript)
+
+## 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 blog-starter-typescript blog-starter-typescript-app
+# or
+yarn create next-app --example blog-starter-typescript blog-starter-typescript-app
+```
+
+Your blog should be up and running on [http://localhost:3000](http://localhost:3000)! If it doesn't work, post on [GitHub discussions](https://github.com/vercel/next.js/discussions).
+
+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)).
+
+# Notes
+
+This blog-starter-typescript uses [Tailwind CSS](https://tailwindcss.com). To control the generated stylesheet's filesize, this example uses Tailwind CSS' v2.0 [`purge` option](https://tailwindcss.com/docs/controlling-file-size/#removing-unused-css) to remove unused CSS.
+
+[Tailwind CSS v2.0 no longer supports Node.js 8 or 10](https://tailwindcss.com/docs/upgrading-to-v2#upgrade-to-node-js-12-13-or-higher). To build your CSS you'll need to ensure you are running Node.js 12.13.0 or higher in both your local and CI environments.
diff --git a/examples/blog-starter-typescript/_posts/dynamic-routing.md b/examples/blog-starter-typescript/_posts/dynamic-routing.md
new file mode 100644
index 0000000000000..b6ef7a26e6ae0
--- /dev/null
+++ b/examples/blog-starter-typescript/_posts/dynamic-routing.md
@@ -0,0 +1,19 @@
+---
+title: 'Dynamic Routing and Static Generation'
+excerpt: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus.'
+coverImage: '/assets/blog/dynamic-routing/cover.jpg'
+date: '2020-03-16T05:35:07.322Z'
+author:
+ name: JJ Kasper
+ picture: '/assets/blog/authors/jj.jpeg'
+ogImage:
+ url: '/assets/blog/dynamic-routing/cover.jpg'
+---
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus. Praesent elementum facilisis leo vel fringilla. Congue mauris rhoncus aenean vel. Egestas sed tempus urna et pharetra pharetra massa massa ultricies.
+
+Venenatis cras sed felis eget velit. Consectetur libero id faucibus nisl tincidunt. Gravida in fermentum et sollicitudin ac orci phasellus egestas tellus. Volutpat consequat mauris nunc congue nisi vitae. Id aliquet risus feugiat in ante metus dictum at tempor. Sed blandit libero volutpat sed cras. Sed odio morbi quis commodo odio aenean sed adipiscing. Velit euismod in pellentesque massa placerat. Mi bibendum neque egestas congue quisque egestas diam in arcu. Nisi lacus sed viverra tellus in. Nibh cras pulvinar mattis nunc sed. Luctus accumsan tortor posuere ac ut consequat semper viverra. Fringilla ut morbi tincidunt augue interdum velit euismod.
+
+## Lorem Ipsum
+
+Tristique senectus et netus et malesuada fames ac turpis. Ridiculous mus mauris vitae ultricies leo integer malesuada nunc vel. In mollis nunc sed id semper. Egestas tellus rutrum tellus pellentesque. Phasellus vestibulum lorem sed risus ultricies tristique nulla. Quis blandit turpis cursus in hac habitasse platea dictumst quisque. Eros donec ac odio tempor orci dapibus ultrices. Aliquam sem et tortor consequat id porta nibh. Adipiscing elit duis tristique sollicitudin nibh sit amet commodo nulla. Diam vulputate ut pharetra sit amet. Ut tellus elementum sagittis vitae et leo. Arcu non odio euismod lacinia at quis risus sed vulputate.
diff --git a/examples/blog-starter-typescript/_posts/hello-world.md b/examples/blog-starter-typescript/_posts/hello-world.md
new file mode 100644
index 0000000000000..8d85a1df8f174
--- /dev/null
+++ b/examples/blog-starter-typescript/_posts/hello-world.md
@@ -0,0 +1,19 @@
+---
+title: 'Learn How to Pre-render Pages Using Static Generation with Next.js'
+excerpt: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus.'
+coverImage: '/assets/blog/hello-world/cover.jpg'
+date: '2020-03-16T05:35:07.322Z'
+author:
+ name: Tim Neutkens
+ picture: '/assets/blog/authors/tim.jpeg'
+ogImage:
+ url: '/assets/blog/hello-world/cover.jpg'
+---
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus. Praesent elementum facilisis leo vel fringilla. Congue mauris rhoncus aenean vel. Egestas sed tempus urna et pharetra pharetra massa massa ultricies.
+
+Venenatis cras sed felis eget velit. Consectetur libero id faucibus nisl tincidunt. Gravida in fermentum et sollicitudin ac orci phasellus egestas tellus. Volutpat consequat mauris nunc congue nisi vitae. Id aliquet risus feugiat in ante metus dictum at tempor. Sed blandit libero volutpat sed cras. Sed odio morbi quis commodo odio aenean sed adipiscing. Velit euismod in pellentesque massa placerat. Mi bibendum neque egestas congue quisque egestas diam in arcu. Nisi lacus sed viverra tellus in. Nibh cras pulvinar mattis nunc sed. Luctus accumsan tortor posuere ac ut consequat semper viverra. Fringilla ut morbi tincidunt augue interdum velit euismod.
+
+## Lorem Ipsum
+
+Tristique senectus et netus et malesuada fames ac turpis. Ridiculous mus mauris vitae ultricies leo integer malesuada nunc vel. In mollis nunc sed id semper. Egestas tellus rutrum tellus pellentesque. Phasellus vestibulum lorem sed risus ultricies tristique nulla. Quis blandit turpis cursus in hac habitasse platea dictumst quisque. Eros donec ac odio tempor orci dapibus ultrices. Aliquam sem et tortor consequat id porta nibh. Adipiscing elit duis tristique sollicitudin nibh sit amet commodo nulla. Diam vulputate ut pharetra sit amet. Ut tellus elementum sagittis vitae et leo. Arcu non odio euismod lacinia at quis risus sed vulputate.
diff --git a/examples/blog-starter-typescript/_posts/preview.md b/examples/blog-starter-typescript/_posts/preview.md
new file mode 100644
index 0000000000000..3d70ba7f99d11
--- /dev/null
+++ b/examples/blog-starter-typescript/_posts/preview.md
@@ -0,0 +1,19 @@
+---
+title: 'Preview Mode for Static Generation'
+excerpt: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus.'
+coverImage: '/assets/blog/preview/cover.jpg'
+date: '2020-03-16T05:35:07.322Z'
+author:
+ name: Joe Haddad
+ picture: '/assets/blog/authors/joe.jpeg'
+ogImage:
+ url: '/assets/blog/preview/cover.jpg'
+---
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus. Praesent elementum facilisis leo vel fringilla. Congue mauris rhoncus aenean vel. Egestas sed tempus urna et pharetra pharetra massa massa ultricies.
+
+Venenatis cras sed felis eget velit. Consectetur libero id faucibus nisl tincidunt. Gravida in fermentum et sollicitudin ac orci phasellus egestas tellus. Volutpat consequat mauris nunc congue nisi vitae. Id aliquet risus feugiat in ante metus dictum at tempor. Sed blandit libero volutpat sed cras. Sed odio morbi quis commodo odio aenean sed adipiscing. Velit euismod in pellentesque massa placerat. Mi bibendum neque egestas congue quisque egestas diam in arcu. Nisi lacus sed viverra tellus in. Nibh cras pulvinar mattis nunc sed. Luctus accumsan tortor posuere ac ut consequat semper viverra. Fringilla ut morbi tincidunt augue interdum velit euismod.
+
+## Lorem Ipsum
+
+Tristique senectus et netus et malesuada fames ac turpis. Ridiculous mus mauris vitae ultricies leo integer malesuada nunc vel. In mollis nunc sed id semper. Egestas tellus rutrum tellus pellentesque. Phasellus vestibulum lorem sed risus ultricies tristique nulla. Quis blandit turpis cursus in hac habitasse platea dictumst quisque. Eros donec ac odio tempor orci dapibus ultrices. Aliquam sem et tortor consequat id porta nibh. Adipiscing elit duis tristique sollicitudin nibh sit amet commodo nulla. Diam vulputate ut pharetra sit amet. Ut tellus elementum sagittis vitae et leo. Arcu non odio euismod lacinia at quis risus sed vulputate.
diff --git a/examples/blog-starter-typescript/components/alert.tsx b/examples/blog-starter-typescript/components/alert.tsx
new file mode 100644
index 0000000000000..f804ff6192868
--- /dev/null
+++ b/examples/blog-starter-typescript/components/alert.tsx
@@ -0,0 +1,48 @@
+import Container from './container'
+import cn from 'classnames'
+import { EXAMPLE_PATH } from '../lib/constants'
+
+type Props = {
+ preview?: boolean
+}
+
+const Alert = ({ preview }: Props) => {
+ return (
+
+
+
+ {preview ? (
+ <>
+ This page is a preview.{' '}
+
+ Click here
+ {' '}
+ to exit preview mode.
+
+ ) : (
+ <>
+ The source code for this blog is{' '}
+
+ available on GitHub
+
+ .
+
+ )}
+
+
+
+
+
+
+ )
+ }
+}
diff --git a/examples/blog-starter-typescript/pages/index.tsx b/examples/blog-starter-typescript/pages/index.tsx
new file mode 100644
index 0000000000000..64a2c6da1bc70
--- /dev/null
+++ b/examples/blog-starter-typescript/pages/index.tsx
@@ -0,0 +1,58 @@
+import Container from '../components/container'
+import MoreStories from '../components/more-stories'
+import HeroPost from '../components/hero-post'
+import Intro from '../components/intro'
+import Layout from '../components/layout'
+import { getAllPosts } from '../lib/api'
+import Head from 'next/head'
+import { CMS_NAME } from '../lib/constants'
+import Post from '../types/post'
+
+type Props = {
+ allPosts: Post[]
+}
+
+const Index = ({ allPosts }: Props) => {
+ const heroPost = allPosts[0]
+ const morePosts = allPosts.slice(1)
+ return (
+ <>
+
+
+ Next.js Blog Example with {CMS_NAME}
+
+
+
+ {heroPost && (
+
+ )}
+ {morePosts.length > 0 && }
+
+
+
+ )
+}
+
+export default Index
+
+export const getStaticProps = async () => {
+ const allPosts = getAllPosts([
+ 'title',
+ 'date',
+ 'slug',
+ 'author',
+ 'coverImage',
+ 'excerpt',
+ ])
+
+ return {
+ props: { allPosts },
+ }
+}
diff --git a/examples/blog-starter-typescript/pages/posts/[slug].tsx b/examples/blog-starter-typescript/pages/posts/[slug].tsx
new file mode 100644
index 0000000000000..1f77e63e773ce
--- /dev/null
+++ b/examples/blog-starter-typescript/pages/posts/[slug].tsx
@@ -0,0 +1,99 @@
+import { useRouter } from 'next/router'
+import ErrorPage from 'next/error'
+import Container from '../../components/container'
+import PostBody from '../../components/post-body'
+import Header from '../../components/header'
+import PostHeader from '../../components/post-header'
+import Layout from '../../components/layout'
+import { getPostBySlug, getAllPosts } from '../../lib/api'
+import PostTitle from '../../components/post-title'
+import Head from 'next/head'
+import { CMS_NAME } from '../../lib/constants'
+import markdownToHtml from '../../lib/markdownToHtml'
+import PostType from '../../types/post'
+
+type Props = {
+ post: PostType
+ morePosts: PostType[]
+ preview?: boolean
+}
+
+const Post = ({ post, morePosts, preview }: Props) => {
+ const router = useRouter()
+ if (!router.isFallback && !post?.slug) {
+ return
+ }
+ return (
+
+
+
+ {router.isFallback ? (
+ Loading…
+ ) : (
+ <>
+
+
+
+ {post.title} | Next.js Blog Example with {CMS_NAME}
+
+
+
+
+
+
+
+ )}
+
+
+ )
+}
+
+export default Post
+
+type Params = {
+ params: {
+ slug: string
+ }
+}
+
+export async function getStaticProps({ params }: Params) {
+ const post = getPostBySlug(params.slug, [
+ 'title',
+ 'date',
+ 'slug',
+ 'author',
+ 'content',
+ 'ogImage',
+ 'coverImage',
+ ])
+ const content = await markdownToHtml(post.content || '')
+
+ return {
+ props: {
+ post: {
+ ...post,
+ content,
+ },
+ },
+ }
+}
+
+export async function getStaticPaths() {
+ const posts = getAllPosts(['slug'])
+
+ return {
+ paths: posts.map((post) => {
+ return {
+ params: {
+ slug: post.slug,
+ },
+ }
+ }),
+ fallback: false,
+ }
+}
diff --git a/examples/blog-starter-typescript/postcss.config.js b/examples/blog-starter-typescript/postcss.config.js
new file mode 100644
index 0000000000000..33ad091d26d8a
--- /dev/null
+++ b/examples/blog-starter-typescript/postcss.config.js
@@ -0,0 +1,6 @@
+module.exports = {
+ plugins: {
+ tailwindcss: {},
+ autoprefixer: {},
+ },
+}
diff --git a/examples/blog-starter-typescript/public/assets/blog/authors/jj.jpeg b/examples/blog-starter-typescript/public/assets/blog/authors/jj.jpeg
new file mode 100644
index 0000000000000..e3d521436a6c1
Binary files /dev/null and b/examples/blog-starter-typescript/public/assets/blog/authors/jj.jpeg differ
diff --git a/examples/blog-starter-typescript/public/assets/blog/authors/joe.jpeg b/examples/blog-starter-typescript/public/assets/blog/authors/joe.jpeg
new file mode 100644
index 0000000000000..d9677ad61c009
Binary files /dev/null and b/examples/blog-starter-typescript/public/assets/blog/authors/joe.jpeg differ
diff --git a/examples/blog-starter-typescript/public/assets/blog/authors/tim.jpeg b/examples/blog-starter-typescript/public/assets/blog/authors/tim.jpeg
new file mode 100644
index 0000000000000..cc49257b82300
Binary files /dev/null and b/examples/blog-starter-typescript/public/assets/blog/authors/tim.jpeg differ
diff --git a/examples/blog-starter-typescript/public/assets/blog/dynamic-routing/cover.jpg b/examples/blog-starter-typescript/public/assets/blog/dynamic-routing/cover.jpg
new file mode 100644
index 0000000000000..c660c92679ee2
Binary files /dev/null and b/examples/blog-starter-typescript/public/assets/blog/dynamic-routing/cover.jpg differ
diff --git a/examples/blog-starter-typescript/public/assets/blog/hello-world/cover.jpg b/examples/blog-starter-typescript/public/assets/blog/hello-world/cover.jpg
new file mode 100644
index 0000000000000..33b7dc4b73ce2
Binary files /dev/null and b/examples/blog-starter-typescript/public/assets/blog/hello-world/cover.jpg differ
diff --git a/examples/blog-starter-typescript/public/assets/blog/preview/cover.jpg b/examples/blog-starter-typescript/public/assets/blog/preview/cover.jpg
new file mode 100644
index 0000000000000..6a975fb36d050
Binary files /dev/null and b/examples/blog-starter-typescript/public/assets/blog/preview/cover.jpg differ
diff --git a/examples/blog-starter-typescript/public/favicon/android-chrome-192x192.png b/examples/blog-starter-typescript/public/favicon/android-chrome-192x192.png
new file mode 100644
index 0000000000000..2f07282a59cda
Binary files /dev/null and b/examples/blog-starter-typescript/public/favicon/android-chrome-192x192.png differ
diff --git a/examples/blog-starter-typescript/public/favicon/android-chrome-512x512.png b/examples/blog-starter-typescript/public/favicon/android-chrome-512x512.png
new file mode 100644
index 0000000000000..dbb0faea84049
Binary files /dev/null and b/examples/blog-starter-typescript/public/favicon/android-chrome-512x512.png differ
diff --git a/examples/blog-starter-typescript/public/favicon/apple-touch-icon.png b/examples/blog-starter-typescript/public/favicon/apple-touch-icon.png
new file mode 100644
index 0000000000000..8f4033b2a8b35
Binary files /dev/null and b/examples/blog-starter-typescript/public/favicon/apple-touch-icon.png differ
diff --git a/examples/blog-starter-typescript/public/favicon/browserconfig.xml b/examples/blog-starter-typescript/public/favicon/browserconfig.xml
new file mode 100644
index 0000000000000..9824d87b11517
--- /dev/null
+++ b/examples/blog-starter-typescript/public/favicon/browserconfig.xml
@@ -0,0 +1,9 @@
+
+
+
+
+
+ #000000
+
+
+
diff --git a/examples/blog-starter-typescript/public/favicon/favicon-16x16.png b/examples/blog-starter-typescript/public/favicon/favicon-16x16.png
new file mode 100644
index 0000000000000..29deaf6716e77
Binary files /dev/null and b/examples/blog-starter-typescript/public/favicon/favicon-16x16.png differ
diff --git a/examples/blog-starter-typescript/public/favicon/favicon-32x32.png b/examples/blog-starter-typescript/public/favicon/favicon-32x32.png
new file mode 100644
index 0000000000000..e3b4277bf093d
Binary files /dev/null and b/examples/blog-starter-typescript/public/favicon/favicon-32x32.png differ
diff --git a/examples/blog-starter-typescript/public/favicon/favicon.ico b/examples/blog-starter-typescript/public/favicon/favicon.ico
new file mode 100644
index 0000000000000..ea2f437d9db65
Binary files /dev/null and b/examples/blog-starter-typescript/public/favicon/favicon.ico differ
diff --git a/examples/blog-starter-typescript/public/favicon/mstile-150x150.png b/examples/blog-starter-typescript/public/favicon/mstile-150x150.png
new file mode 100644
index 0000000000000..f2dfd904bf1be
Binary files /dev/null and b/examples/blog-starter-typescript/public/favicon/mstile-150x150.png differ
diff --git a/examples/blog-starter-typescript/public/favicon/safari-pinned-tab.svg b/examples/blog-starter-typescript/public/favicon/safari-pinned-tab.svg
new file mode 100644
index 0000000000000..72ab6e050cb11
--- /dev/null
+++ b/examples/blog-starter-typescript/public/favicon/safari-pinned-tab.svg
@@ -0,0 +1,33 @@
+
+
+
diff --git a/examples/blog-starter-typescript/public/favicon/site.webmanifest b/examples/blog-starter-typescript/public/favicon/site.webmanifest
new file mode 100644
index 0000000000000..a672d9a233c59
--- /dev/null
+++ b/examples/blog-starter-typescript/public/favicon/site.webmanifest
@@ -0,0 +1,19 @@
+{
+ "name": "Next.js",
+ "short_name": "Next.js",
+ "icons": [
+ {
+ "src": "/favicons/android-chrome-192x192.png",
+ "sizes": "192x192",
+ "type": "image/png"
+ },
+ {
+ "src": "/favicons/android-chrome-512x512.png",
+ "sizes": "512x512",
+ "type": "image/png"
+ }
+ ],
+ "theme_color": "#000000",
+ "background_color": "#000000",
+ "display": "standalone"
+}
diff --git a/examples/blog-starter-typescript/styles/index.css b/examples/blog-starter-typescript/styles/index.css
new file mode 100644
index 0000000000000..719e6c05b0d76
--- /dev/null
+++ b/examples/blog-starter-typescript/styles/index.css
@@ -0,0 +1,15 @@
+@tailwind base;
+
+/* Write your own custom base styles here */
+
+/* Start purging... */
+@tailwind components;
+/* Stop purging. */
+
+/* Write you own custom component styles here */
+
+/* Start purging... */
+@tailwind utilities;
+/* Stop purging. */
+
+/* Your own custom utilities */
diff --git a/examples/blog-starter-typescript/tailwind.config.js b/examples/blog-starter-typescript/tailwind.config.js
new file mode 100644
index 0000000000000..d7d1c3ee7f005
--- /dev/null
+++ b/examples/blog-starter-typescript/tailwind.config.js
@@ -0,0 +1,33 @@
+module.exports = {
+ purge: ['./components/**/*.tsx', './pages/**/*.tsx'],
+ theme: {
+ extend: {
+ colors: {
+ 'accent-1': '#FAFAFA',
+ 'accent-2': '#EAEAEA',
+ 'accent-7': '#333',
+ success: '#0070f3',
+ cyan: '#79FFE1',
+ },
+ spacing: {
+ 28: '7rem',
+ },
+ letterSpacing: {
+ tighter: '-.04em',
+ },
+ lineHeight: {
+ tight: 1.2,
+ },
+ fontSize: {
+ '5xl': '2.5rem',
+ '6xl': '2.75rem',
+ '7xl': '4.5rem',
+ '8xl': '6.25rem',
+ },
+ boxShadow: {
+ small: '0 5px 10px rgba(0, 0, 0, 0.12)',
+ medium: '0 8px 30px rgba(0, 0, 0, 0.12)',
+ },
+ },
+ },
+}
diff --git a/examples/blog-starter-typescript/tsconfig.json b/examples/blog-starter-typescript/tsconfig.json
new file mode 100644
index 0000000000000..645da11f036e1
--- /dev/null
+++ b/examples/blog-starter-typescript/tsconfig.json
@@ -0,0 +1,19 @@
+{
+ "compilerOptions": {
+ "target": "es5",
+ "module": "esnext",
+ "jsx": "preserve",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "noEmit": true,
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true
+ },
+ "exclude": ["node_modules"],
+ "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"]
+}
diff --git a/examples/blog-starter-typescript/types/author.ts b/examples/blog-starter-typescript/types/author.ts
new file mode 100644
index 0000000000000..4d9892b341508
--- /dev/null
+++ b/examples/blog-starter-typescript/types/author.ts
@@ -0,0 +1,6 @@
+type Author = {
+ name: string
+ picture: string
+}
+
+export default Author
diff --git a/examples/blog-starter-typescript/types/post.ts b/examples/blog-starter-typescript/types/post.ts
new file mode 100644
index 0000000000000..a5f7bb91dd1a4
--- /dev/null
+++ b/examples/blog-starter-typescript/types/post.ts
@@ -0,0 +1,16 @@
+import Author from './author'
+
+type PostType = {
+ slug: string
+ title: string
+ date: string
+ coverImage: string
+ author: Author
+ excerpt: string
+ ogImage: {
+ url: string
+ }
+ content: string
+}
+
+export default PostType
diff --git a/examples/blog-starter/.gitignore b/examples/blog-starter/.gitignore
index 5900fa96e8d3e..1437c53f70bc2 100644
--- a/examples/blog-starter/.gitignore
+++ b/examples/blog-starter/.gitignore
@@ -1,2 +1,34 @@
-.env
-.now
\ No newline at end of file
+# 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/blog-starter/README.md b/examples/blog-starter/README.md
index 76b4acf2353fa..0b9ab5a1d932b 100644
--- a/examples/blog-starter/README.md
+++ b/examples/blog-starter/README.md
@@ -1,55 +1,63 @@
# A statically generated blog example using Next.js and Markdown
-This example showcases Next.js's [Static Generation](https://nextjs.org/docs/basic-features/pages) feature using markdown files as the data source.
+This example showcases Next.js's [Static Generation](https://nextjs.org/docs/basic-features/pages) feature using Markdown files as the data source.
-The blog posts are stored in `/_posts` as markdown files with front matter support. Adding a new markdown file in there will create a new blog post.
+The blog posts are stored in `/_posts` as Markdown files with front matter support. Adding a new Markdown file in there will create a new blog post.
-To create the blog posts we use [`remark`](https://github.com/remarkjs/remark) and [`remark-html`](https://github.com/remarkjs/remark-html) to convert the markdown files into an HTML string, and then send it down as a prop to the page. The metadata of every post is handled by [`gray-matter`](https://github.com/jonschlinkert/gray-matter) and also sent in props to the page.
+To create the blog posts we use [`remark`](https://github.com/remarkjs/remark) and [`remark-html`](https://github.com/remarkjs/remark-html) to convert the Markdown files into an HTML string, and then send it down as a prop to the page. The metadata of every post is handled by [`gray-matter`](https://github.com/jonschlinkert/gray-matter) and also sent in props to the page.
+
+## Preview
+
+Preview the example live on [StackBlitz](http://stackblitz.com/):
+
+[](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/blog-starter)
## Demo
-[https://next-blog-starter.now.sh/](https://next-blog-starter.now.sh/)
+[https://next-blog-starter.vercel.app/](https://next-blog-starter.vercel.app/)
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/blog-starter&project-name=blog-starter&repository-name=blog-starter)
### Related examples
+- [WordPress](/examples/cms-wordpress)
- [DatoCMS](/examples/cms-datocms)
- [Sanity](/examples/cms-sanity)
- [TakeShape](/examples/cms-takeshape)
- [Prismic](/examples/cms-prismic)
+- [Contentful](/examples/cms-contentful)
+- [Strapi](/examples/cms-strapi)
+- [Agility CMS](/examples/cms-agilitycms)
+- [Cosmic](/examples/cms-cosmic)
+- [ButterCMS](/examples/cms-buttercms)
+- [Storyblok](/examples/cms-storyblok)
+- [GraphCMS](/examples/cms-graphcms)
+- [Kontent](/examples/cms-kontent)
## 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:
+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
-npm init next-app --example blog-starter blog-starter-app
-# or
-yarn create next-app --example blog-starter blog-starter-app
```
+npx create-next-app --example blog-starter blog-starter-app
-### Download manually
+```
-Download the example:
+or
-```bash
-curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/blog-starter
-cd blog-starter
```
+yarn create next-app --example blog-starter blog-starter-app
-Install dependencies and run the example:
-
-```bash
-npm install
-npm run dev
+```
-# or
+Your blog should be up and running on [http://localhost:3000](http://localhost:3000)! If it doesn't work, post on [GitHub discussions](https://github.com/vercel/next.js/discussions).
-yarn install
-yarn dev
-```
+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)).
-Your blog should be up and running on [http://localhost:3000](http://localhost:3000)! If it doesn't work, post on [GitHub discussions](https://github.com/zeit/next.js/discussions).
+# Notes
-Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+This blog-starter uses [Tailwind CSS](https://tailwindcss.com). To control the generated stylesheet's filesize, this example uses Tailwind CSS' v2.0 [`purge` option](https://tailwindcss.com/docs/controlling-file-size/#removing-unused-css) to remove unused CSS.
diff --git a/examples/blog-starter/_posts/dynamic-routing.md b/examples/blog-starter/_posts/dynamic-routing.md
index bed83f440fc8f..b6ef7a26e6ae0 100644
--- a/examples/blog-starter/_posts/dynamic-routing.md
+++ b/examples/blog-starter/_posts/dynamic-routing.md
@@ -1,6 +1,6 @@
---
title: 'Dynamic Routing and Static Generation'
-excerpt: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilisi morbi tempus.'
+excerpt: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus.'
coverImage: '/assets/blog/dynamic-routing/cover.jpg'
date: '2020-03-16T05:35:07.322Z'
author:
@@ -10,10 +10,10 @@ ogImage:
url: '/assets/blog/dynamic-routing/cover.jpg'
---
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilisi morbi tempus. Praesent elementum facilisis leo vel fringilla. Congue mauris rhoncus aenean vel. Egestas sed tempus urna et pharetra pharetra massa massa ultricies.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus. Praesent elementum facilisis leo vel fringilla. Congue mauris rhoncus aenean vel. Egestas sed tempus urna et pharetra pharetra massa massa ultricies.
Venenatis cras sed felis eget velit. Consectetur libero id faucibus nisl tincidunt. Gravida in fermentum et sollicitudin ac orci phasellus egestas tellus. Volutpat consequat mauris nunc congue nisi vitae. Id aliquet risus feugiat in ante metus dictum at tempor. Sed blandit libero volutpat sed cras. Sed odio morbi quis commodo odio aenean sed adipiscing. Velit euismod in pellentesque massa placerat. Mi bibendum neque egestas congue quisque egestas diam in arcu. Nisi lacus sed viverra tellus in. Nibh cras pulvinar mattis nunc sed. Luctus accumsan tortor posuere ac ut consequat semper viverra. Fringilla ut morbi tincidunt augue interdum velit euismod.
## Lorem Ipsum
-Tristique senectus et netus et malesuada fames ac turpis. Ridiculus mus mauris vitae ultricies leo integer malesuada nunc vel. In mollis nunc sed id semper. Egestas tellus rutrum tellus pellentesque. Phasellus vestibulum lorem sed risus ultricies tristique nulla. Quis blandit turpis cursus in hac habitasse platea dictumst quisque. Eros donec ac odio tempor orci dapibus ultrices. Aliquam sem et tortor consequat id porta nibh. Adipiscing elit duis tristique sollicitudin nibh sit amet commodo nulla. Diam vulputate ut pharetra sit amet. Ut tellus elementum sagittis vitae et leo. Arcu non odio euismod lacinia at quis risus sed vulputate.
+Tristique senectus et netus et malesuada fames ac turpis. Ridiculous mus mauris vitae ultricies leo integer malesuada nunc vel. In mollis nunc sed id semper. Egestas tellus rutrum tellus pellentesque. Phasellus vestibulum lorem sed risus ultricies tristique nulla. Quis blandit turpis cursus in hac habitasse platea dictumst quisque. Eros donec ac odio tempor orci dapibus ultrices. Aliquam sem et tortor consequat id porta nibh. Adipiscing elit duis tristique sollicitudin nibh sit amet commodo nulla. Diam vulputate ut pharetra sit amet. Ut tellus elementum sagittis vitae et leo. Arcu non odio euismod lacinia at quis risus sed vulputate.
diff --git a/examples/blog-starter/_posts/hello-world.md b/examples/blog-starter/_posts/hello-world.md
index 005b883a60ae6..8d85a1df8f174 100644
--- a/examples/blog-starter/_posts/hello-world.md
+++ b/examples/blog-starter/_posts/hello-world.md
@@ -1,6 +1,6 @@
---
title: 'Learn How to Pre-render Pages Using Static Generation with Next.js'
-excerpt: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilisi morbi tempus.'
+excerpt: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus.'
coverImage: '/assets/blog/hello-world/cover.jpg'
date: '2020-03-16T05:35:07.322Z'
author:
@@ -10,10 +10,10 @@ ogImage:
url: '/assets/blog/hello-world/cover.jpg'
---
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilisi morbi tempus. Praesent elementum facilisis leo vel fringilla. Congue mauris rhoncus aenean vel. Egestas sed tempus urna et pharetra pharetra massa massa ultricies.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus. Praesent elementum facilisis leo vel fringilla. Congue mauris rhoncus aenean vel. Egestas sed tempus urna et pharetra pharetra massa massa ultricies.
Venenatis cras sed felis eget velit. Consectetur libero id faucibus nisl tincidunt. Gravida in fermentum et sollicitudin ac orci phasellus egestas tellus. Volutpat consequat mauris nunc congue nisi vitae. Id aliquet risus feugiat in ante metus dictum at tempor. Sed blandit libero volutpat sed cras. Sed odio morbi quis commodo odio aenean sed adipiscing. Velit euismod in pellentesque massa placerat. Mi bibendum neque egestas congue quisque egestas diam in arcu. Nisi lacus sed viverra tellus in. Nibh cras pulvinar mattis nunc sed. Luctus accumsan tortor posuere ac ut consequat semper viverra. Fringilla ut morbi tincidunt augue interdum velit euismod.
## Lorem Ipsum
-Tristique senectus et netus et malesuada fames ac turpis. Ridiculus mus mauris vitae ultricies leo integer malesuada nunc vel. In mollis nunc sed id semper. Egestas tellus rutrum tellus pellentesque. Phasellus vestibulum lorem sed risus ultricies tristique nulla. Quis blandit turpis cursus in hac habitasse platea dictumst quisque. Eros donec ac odio tempor orci dapibus ultrices. Aliquam sem et tortor consequat id porta nibh. Adipiscing elit duis tristique sollicitudin nibh sit amet commodo nulla. Diam vulputate ut pharetra sit amet. Ut tellus elementum sagittis vitae et leo. Arcu non odio euismod lacinia at quis risus sed vulputate.
+Tristique senectus et netus et malesuada fames ac turpis. Ridiculous mus mauris vitae ultricies leo integer malesuada nunc vel. In mollis nunc sed id semper. Egestas tellus rutrum tellus pellentesque. Phasellus vestibulum lorem sed risus ultricies tristique nulla. Quis blandit turpis cursus in hac habitasse platea dictumst quisque. Eros donec ac odio tempor orci dapibus ultrices. Aliquam sem et tortor consequat id porta nibh. Adipiscing elit duis tristique sollicitudin nibh sit amet commodo nulla. Diam vulputate ut pharetra sit amet. Ut tellus elementum sagittis vitae et leo. Arcu non odio euismod lacinia at quis risus sed vulputate.
diff --git a/examples/blog-starter/_posts/preview.md b/examples/blog-starter/_posts/preview.md
index 385082606e9b6..3d70ba7f99d11 100644
--- a/examples/blog-starter/_posts/preview.md
+++ b/examples/blog-starter/_posts/preview.md
@@ -1,6 +1,6 @@
---
title: 'Preview Mode for Static Generation'
-excerpt: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilisi morbi tempus.'
+excerpt: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus.'
coverImage: '/assets/blog/preview/cover.jpg'
date: '2020-03-16T05:35:07.322Z'
author:
@@ -10,10 +10,10 @@ ogImage:
url: '/assets/blog/preview/cover.jpg'
---
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilisi morbi tempus. Praesent elementum facilisis leo vel fringilla. Congue mauris rhoncus aenean vel. Egestas sed tempus urna et pharetra pharetra massa massa ultricies.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus. Praesent elementum facilisis leo vel fringilla. Congue mauris rhoncus aenean vel. Egestas sed tempus urna et pharetra pharetra massa massa ultricies.
Venenatis cras sed felis eget velit. Consectetur libero id faucibus nisl tincidunt. Gravida in fermentum et sollicitudin ac orci phasellus egestas tellus. Volutpat consequat mauris nunc congue nisi vitae. Id aliquet risus feugiat in ante metus dictum at tempor. Sed blandit libero volutpat sed cras. Sed odio morbi quis commodo odio aenean sed adipiscing. Velit euismod in pellentesque massa placerat. Mi bibendum neque egestas congue quisque egestas diam in arcu. Nisi lacus sed viverra tellus in. Nibh cras pulvinar mattis nunc sed. Luctus accumsan tortor posuere ac ut consequat semper viverra. Fringilla ut morbi tincidunt augue interdum velit euismod.
## Lorem Ipsum
-Tristique senectus et netus et malesuada fames ac turpis. Ridiculus mus mauris vitae ultricies leo integer malesuada nunc vel. In mollis nunc sed id semper. Egestas tellus rutrum tellus pellentesque. Phasellus vestibulum lorem sed risus ultricies tristique nulla. Quis blandit turpis cursus in hac habitasse platea dictumst quisque. Eros donec ac odio tempor orci dapibus ultrices. Aliquam sem et tortor consequat id porta nibh. Adipiscing elit duis tristique sollicitudin nibh sit amet commodo nulla. Diam vulputate ut pharetra sit amet. Ut tellus elementum sagittis vitae et leo. Arcu non odio euismod lacinia at quis risus sed vulputate.
+Tristique senectus et netus et malesuada fames ac turpis. Ridiculous mus mauris vitae ultricies leo integer malesuada nunc vel. In mollis nunc sed id semper. Egestas tellus rutrum tellus pellentesque. Phasellus vestibulum lorem sed risus ultricies tristique nulla. Quis blandit turpis cursus in hac habitasse platea dictumst quisque. Eros donec ac odio tempor orci dapibus ultrices. Aliquam sem et tortor consequat id porta nibh. Adipiscing elit duis tristique sollicitudin nibh sit amet commodo nulla. Diam vulputate ut pharetra sit amet. Ut tellus elementum sagittis vitae et leo. Arcu non odio euismod lacinia at quis risus sed vulputate.
diff --git a/examples/blog-starter/components/alert.js b/examples/blog-starter/components/alert.js
index 3530e66e59c8d..b924cb097f169 100644
--- a/examples/blog-starter/components/alert.js
+++ b/examples/blog-starter/components/alert.js
@@ -14,7 +14,7 @@ export default function Alert({ preview }) {
+import Image from 'next/image'
+
+function Avatar() {
+ return