Move upgrading guide to /docs (#10727)
* Move UPGRADING.md to docs * Add upgrading guide to manifest.json * Update title * Move to docs/upgrading * Update UPGRADING.md * Update docs/manifest.json * Update UPGRADING.md Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
This commit is contained in:
parent
b2624012ea
commit
709aac1e96
3 changed files with 224 additions and 213 deletions
214
UPGRADING.md
214
UPGRADING.md
|
@ -1,213 +1 @@
|
||||||
# Migrating from v8 to v9
|
This document has been moved to [nextjs.org/docs/upgrading](https://nextjs.org/docs/upgrading). It's also available in this repository on [/docs/upgrading.md](/docs/upgrading.md).
|
||||||
|
|
||||||
## Preamble
|
|
||||||
|
|
||||||
#### Production Deployment on ZEIT Now v2
|
|
||||||
|
|
||||||
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://github.com/zeit/next.js#dynamic-routing).
|
|
||||||
|
|
||||||
Next.js 9's dynamic routes are **automatically configured on [Now](https://zeit.co/now)** and do not require any `now.json` customization.
|
|
||||||
|
|
||||||
You can read more about [Dynamic Routing here](https://github.com/zeit/next.js#dynamic-routing).
|
|
||||||
|
|
||||||
#### Check your Custom <App> (`pages/_app.js`)
|
|
||||||
|
|
||||||
If you previously copied the [Custom `<App>`](https://nextjs.org/docs#custom-app) 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!
|
|
||||||
|
|
||||||
The following `getInitialProps` does nothing and may be removed:
|
|
||||||
|
|
||||||
```js
|
|
||||||
class MyApp extends App {
|
|
||||||
// Remove me, I do nothing!
|
|
||||||
static async getInitialProps({ Component, ctx }) {
|
|
||||||
let pageProps = {}
|
|
||||||
|
|
||||||
if (Component.getInitialProps) {
|
|
||||||
pageProps = await Component.getInitialProps(ctx)
|
|
||||||
}
|
|
||||||
|
|
||||||
return { pageProps }
|
|
||||||
}
|
|
||||||
|
|
||||||
render() {
|
|
||||||
// ... etc
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Breaking Changes
|
|
||||||
|
|
||||||
#### `@zeit/next-typescript` is no longer necessary
|
|
||||||
|
|
||||||
Next.js will now ignore usage `@zeit/next-typescript` and warn you to remove it. Please remove this plugin from your `next.config.js`.
|
|
||||||
|
|
||||||
Remove references to `@zeit/next-typescript/babel` from your custom `.babelrc` (if present).
|
|
||||||
|
|
||||||
Usage of [`fork-ts-checker-webpack-plugin`](https://github.com/Realytics/fork-ts-checker-webpack-plugin/issues) should also be removed from your `next.config.js`.
|
|
||||||
|
|
||||||
TypeScript Definitions are published with the `next` package, so you need to uninstall `@types/next` as they would conflict.
|
|
||||||
|
|
||||||
The following types are different:
|
|
||||||
|
|
||||||
> This list was created by the community to help you upgrade, if you find other differences please send a pull-request to this list to help other users.
|
|
||||||
|
|
||||||
From:
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
import { NextContext } from 'next'
|
|
||||||
import { NextAppContext, DefaultAppIProps } from 'next/app'
|
|
||||||
import { NextDocumentContext, DefaultDocumentIProps } from 'next/document'
|
|
||||||
```
|
|
||||||
|
|
||||||
to
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
import { NextPageContext } from 'next'
|
|
||||||
import { AppContext, AppInitialProps } from 'next/app'
|
|
||||||
import { DocumentContext, DocumentInitialProps } from 'next/document'
|
|
||||||
```
|
|
||||||
|
|
||||||
#### The `config` key is now a special 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.
|
|
||||||
|
|
||||||
You must rename a non-Next.js-purposed `config` export to something different.
|
|
||||||
|
|
||||||
#### `next/dynamic` no longer renders "loading..." by default while loading
|
|
||||||
|
|
||||||
Dynamic components will not render anything by default while loading. You can still customize this behavior by setting the `loading` property:
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
import dynamic from 'next/dynamic'
|
|
||||||
|
|
||||||
const DynamicComponentWithCustomLoading = dynamic(
|
|
||||||
() => import('../components/hello2'),
|
|
||||||
{
|
|
||||||
loading: () => <p>Loading</p>,
|
|
||||||
}
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
#### `withAmp` has been removed in favor of an exported configuration object
|
|
||||||
|
|
||||||
Next.js now has the concept of page-level configuration, so the `withAmp` higher-order component has been removed for consistency.
|
|
||||||
|
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
To perform this migration by hand, or view what the codemod will produce, see below:
|
|
||||||
|
|
||||||
**Before**
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
import { withAmp } from 'next/amp'
|
|
||||||
|
|
||||||
function Home() {
|
|
||||||
return <h1>My AMP Page</h1>
|
|
||||||
}
|
|
||||||
|
|
||||||
export default withAmp(Home)
|
|
||||||
// or
|
|
||||||
export default withAmp(Home, { hybrid: true })
|
|
||||||
```
|
|
||||||
|
|
||||||
**After**
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
export default function Home() {
|
|
||||||
return <h1>My AMP Page</h1>
|
|
||||||
}
|
|
||||||
|
|
||||||
export const config = {
|
|
||||||
amp: true,
|
|
||||||
// or
|
|
||||||
amp: 'hybrid',
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### `next export` no longer exports pages as `index.html`
|
|
||||||
|
|
||||||
Previously, exporting `pages/about.js` would result in `out/about/index.html`. This behavior has been changed to result in `out/about.html`.
|
|
||||||
|
|
||||||
You can revert to the previous behavior by creating a `next.config.js` with the following content:
|
|
||||||
|
|
||||||
```js
|
|
||||||
// next.config.js
|
|
||||||
module.exports = {
|
|
||||||
exportTrailingSlash: true,
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### `./pages/api/` is treated differently
|
|
||||||
|
|
||||||
Pages in `./pages/api/` are now considered [API Routes](https://nextjs.org/blog/next-9#api-routes).
|
|
||||||
Pages in this directory will no longer contain a client-side bundle.
|
|
||||||
|
|
||||||
## Deprecated Features
|
|
||||||
|
|
||||||
#### `next/dynamic` has deprecated loading multiple modules at once
|
|
||||||
|
|
||||||
The ability to load multiple modules at once has been deprecated in `next/dynamic` to be closer to React's implementation (`React.lazy` and `Suspense`).
|
|
||||||
|
|
||||||
Updating code that relies on this behavior is relatively straightforward! We've provided an example of a before/after to help you migrate your application:
|
|
||||||
|
|
||||||
**Before**
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
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),
|
|
||||||
}
|
|
||||||
|
|
||||||
return components
|
|
||||||
},
|
|
||||||
render: (props, { Hello1, Hello2 }) => (
|
|
||||||
<div>
|
|
||||||
<h1>{props.title}</h1>
|
|
||||||
<Hello1 />
|
|
||||||
<Hello2 />
|
|
||||||
</div>
|
|
||||||
),
|
|
||||||
})
|
|
||||||
|
|
||||||
function DynamicBundle() {
|
|
||||||
return <HelloBundle title="Dynamic Bundle" />
|
|
||||||
}
|
|
||||||
|
|
||||||
export default DynamicBundle
|
|
||||||
```
|
|
||||||
|
|
||||||
**After**
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
import dynamic from 'next/dynamic'
|
|
||||||
|
|
||||||
const Hello1 = dynamic(() => import('../components/hello1'))
|
|
||||||
const Hello2 = dynamic(() => import('../components/hello2'))
|
|
||||||
|
|
||||||
function HelloBundle({ title }) {
|
|
||||||
return (
|
|
||||||
<div>
|
|
||||||
<h1>{title}</h1>
|
|
||||||
<Hello1 />
|
|
||||||
<Hello2 />
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
|
|
||||||
function DynamicBundle() {
|
|
||||||
return <HelloBundle title="Dynamic Bundle" />
|
|
||||||
}
|
|
||||||
|
|
||||||
export default DynamicBundle
|
|
||||||
```
|
|
||||||
|
|
|
@ -147,6 +147,10 @@
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
"title": "Upgrade Guide",
|
||||||
|
"path": "/docs/upgrading.md"
|
||||||
|
},
|
||||||
{ "title": "FAQ", "path": "/docs/faq.md" }
|
{ "title": "FAQ", "path": "/docs/faq.md" }
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
|
|
219
docs/upgrading.md
Normal file
219
docs/upgrading.md
Normal file
|
@ -0,0 +1,219 @@
|
||||||
|
---
|
||||||
|
description: Learn how to upgrade Next.js.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Upgrade Guide
|
||||||
|
|
||||||
|
## Upgrading from version 8 to 9.0.x
|
||||||
|
|
||||||
|
### Preamble
|
||||||
|
|
||||||
|
#### Production Deployment on ZEIT Now v2
|
||||||
|
|
||||||
|
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://github.com/zeit/next.js#dynamic-routing).
|
||||||
|
|
||||||
|
Next.js 9's dynamic routes are **automatically configured on [Now](https://zeit.co/now)** and do not require any `now.json` customization.
|
||||||
|
|
||||||
|
You can read more about [Dynamic Routing here](https://github.com/zeit/next.js#dynamic-routing).
|
||||||
|
|
||||||
|
#### Check your Custom <App> (`pages/_app.js`)
|
||||||
|
|
||||||
|
If you previously copied the [Custom `<App>`](https://nextjs.org/docs#custom-app) 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!
|
||||||
|
|
||||||
|
The following `getInitialProps` does nothing and may be removed:
|
||||||
|
|
||||||
|
```js
|
||||||
|
class MyApp extends App {
|
||||||
|
// Remove me, I do nothing!
|
||||||
|
static async getInitialProps({ Component, ctx }) {
|
||||||
|
let pageProps = {}
|
||||||
|
|
||||||
|
if (Component.getInitialProps) {
|
||||||
|
pageProps = await Component.getInitialProps(ctx)
|
||||||
|
}
|
||||||
|
|
||||||
|
return { pageProps }
|
||||||
|
}
|
||||||
|
|
||||||
|
render() {
|
||||||
|
// ... etc
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Breaking Changes
|
||||||
|
|
||||||
|
#### `@zeit/next-typescript` is no longer necessary
|
||||||
|
|
||||||
|
Next.js will now ignore usage `@zeit/next-typescript` and warn you to remove it. Please remove this plugin from your `next.config.js`.
|
||||||
|
|
||||||
|
Remove references to `@zeit/next-typescript/babel` from your custom `.babelrc` (if present).
|
||||||
|
|
||||||
|
Usage of [`fork-ts-checker-webpack-plugin`](https://github.com/Realytics/fork-ts-checker-webpack-plugin/issues) should also be removed from your `next.config.js`.
|
||||||
|
|
||||||
|
TypeScript Definitions are published with the `next` package, so you need to uninstall `@types/next` as they would conflict.
|
||||||
|
|
||||||
|
The following types are different:
|
||||||
|
|
||||||
|
> This list was created by the community to help you upgrade, if you find other differences please send a pull-request to this list to help other users.
|
||||||
|
|
||||||
|
From:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { NextContext } from 'next'
|
||||||
|
import { NextAppContext, DefaultAppIProps } from 'next/app'
|
||||||
|
import { NextDocumentContext, DefaultDocumentIProps } from 'next/document'
|
||||||
|
```
|
||||||
|
|
||||||
|
to
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { NextPageContext } from 'next'
|
||||||
|
import { AppContext, AppInitialProps } from 'next/app'
|
||||||
|
import { DocumentContext, DocumentInitialProps } from 'next/document'
|
||||||
|
```
|
||||||
|
|
||||||
|
#### The `config` key is now a special 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.
|
||||||
|
|
||||||
|
You must rename a non-Next.js-purposed `config` export to something different.
|
||||||
|
|
||||||
|
#### `next/dynamic` no longer renders "loading..." by default while loading
|
||||||
|
|
||||||
|
Dynamic components will not render anything by default while loading. You can still customize this behavior by setting the `loading` property:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
import dynamic from 'next/dynamic'
|
||||||
|
|
||||||
|
const DynamicComponentWithCustomLoading = dynamic(
|
||||||
|
() => import('../components/hello2'),
|
||||||
|
{
|
||||||
|
loading: () => <p>Loading</p>,
|
||||||
|
}
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `withAmp` has been removed in favor of an exported configuration object
|
||||||
|
|
||||||
|
Next.js now has the concept of page-level configuration, so the `withAmp` higher-order component has been removed for consistency.
|
||||||
|
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
To perform this migration by hand, or view what the codemod will produce, see below:
|
||||||
|
|
||||||
|
**Before**
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
import { withAmp } from 'next/amp'
|
||||||
|
|
||||||
|
function Home() {
|
||||||
|
return <h1>My AMP Page</h1>
|
||||||
|
}
|
||||||
|
|
||||||
|
export default withAmp(Home)
|
||||||
|
// or
|
||||||
|
export default withAmp(Home, { hybrid: true })
|
||||||
|
```
|
||||||
|
|
||||||
|
**After**
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
export default function Home() {
|
||||||
|
return <h1>My AMP Page</h1>
|
||||||
|
}
|
||||||
|
|
||||||
|
export const config = {
|
||||||
|
amp: true,
|
||||||
|
// or
|
||||||
|
amp: 'hybrid',
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `next export` no longer exports pages as `index.html`
|
||||||
|
|
||||||
|
Previously, exporting `pages/about.js` would result in `out/about/index.html`. This behavior has been changed to result in `out/about.html`.
|
||||||
|
|
||||||
|
You can revert to the previous behavior by creating a `next.config.js` with the following content:
|
||||||
|
|
||||||
|
```js
|
||||||
|
// next.config.js
|
||||||
|
module.exports = {
|
||||||
|
exportTrailingSlash: true,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `./pages/api/` is treated differently
|
||||||
|
|
||||||
|
Pages in `./pages/api/` are now considered [API Routes](https://nextjs.org/blog/next-9#api-routes).
|
||||||
|
Pages in this directory will no longer contain a client-side bundle.
|
||||||
|
|
||||||
|
## Deprecated Features
|
||||||
|
|
||||||
|
#### `next/dynamic` has deprecated loading multiple modules at once
|
||||||
|
|
||||||
|
The ability to load multiple modules at once has been deprecated in `next/dynamic` to be closer to React's implementation (`React.lazy` and `Suspense`).
|
||||||
|
|
||||||
|
Updating code that relies on this behavior is relatively straightforward! We've provided an example of a before/after to help you migrate your application:
|
||||||
|
|
||||||
|
**Before**
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
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),
|
||||||
|
}
|
||||||
|
|
||||||
|
return components
|
||||||
|
},
|
||||||
|
render: (props, { Hello1, Hello2 }) => (
|
||||||
|
<div>
|
||||||
|
<h1>{props.title}</h1>
|
||||||
|
<Hello1 />
|
||||||
|
<Hello2 />
|
||||||
|
</div>
|
||||||
|
),
|
||||||
|
})
|
||||||
|
|
||||||
|
function DynamicBundle() {
|
||||||
|
return <HelloBundle title="Dynamic Bundle" />
|
||||||
|
}
|
||||||
|
|
||||||
|
export default DynamicBundle
|
||||||
|
```
|
||||||
|
|
||||||
|
**After**
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
import dynamic from 'next/dynamic'
|
||||||
|
|
||||||
|
const Hello1 = dynamic(() => import('../components/hello1'))
|
||||||
|
const Hello2 = dynamic(() => import('../components/hello2'))
|
||||||
|
|
||||||
|
function HelloBundle({ title }) {
|
||||||
|
return (
|
||||||
|
<div>
|
||||||
|
<h1>{title}</h1>
|
||||||
|
<Hello1 />
|
||||||
|
<Hello2 />
|
||||||
|
</div>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
function DynamicBundle() {
|
||||||
|
return <HelloBundle title="Dynamic Bundle" />
|
||||||
|
}
|
||||||
|
|
||||||
|
export default DynamicBundle
|
||||||
|
```
|
Loading…
Reference in a new issue