|
1 | | -# Migrating from v8 to v9 |
2 | | - |
3 | | -## Preamble |
4 | | - |
5 | | -#### Production Deployment on ZEIT Now v2 |
6 | | - |
7 | | -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). |
8 | | - |
9 | | -Next.js 9's dynamic routes are **automatically configured on [Now](https://zeit.co/now)** and do not require any `now.json` customization. |
10 | | - |
11 | | -You can read more about [Dynamic Routing here](https://github.com/zeit/next.js#dynamic-routing). |
12 | | - |
13 | | -#### Check your Custom <App> (`pages/_app.js`) |
14 | | - |
15 | | -If you previously copied the [Custom `<App>`](https://nextjs.org/docs#custom-app) example, you may be able to remove your `getInitialProps`. |
16 | | - |
17 | | -Removing `getInitialProps` from `pages/_app.js` (when possible) is important to leverage new Next.js features! |
18 | | - |
19 | | -The following `getInitialProps` does nothing and may be removed: |
20 | | - |
21 | | -```js |
22 | | -class MyApp extends App { |
23 | | - // Remove me, I do nothing! |
24 | | - static async getInitialProps({ Component, ctx }) { |
25 | | - let pageProps = {} |
26 | | - |
27 | | - if (Component.getInitialProps) { |
28 | | - pageProps = await Component.getInitialProps(ctx) |
29 | | - } |
30 | | - |
31 | | - return { pageProps } |
32 | | - } |
33 | | - |
34 | | - render() { |
35 | | - // ... etc |
36 | | - } |
37 | | -} |
38 | | -``` |
39 | | - |
40 | | -## Breaking Changes |
41 | | - |
42 | | -#### `@zeit/next-typescript` is no longer necessary |
43 | | - |
44 | | -Next.js will now ignore usage `@zeit/next-typescript` and warn you to remove it. Please remove this plugin from your `next.config.js`. |
45 | | - |
46 | | -Remove references to `@zeit/next-typescript/babel` from your custom `.babelrc` (if present). |
47 | | - |
48 | | -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`. |
49 | | - |
50 | | -TypeScript Definitions are published with the `next` package, so you need to uninstall `@types/next` as they would conflict. |
51 | | - |
52 | | -The following types are different: |
53 | | - |
54 | | -> 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. |
55 | | -
|
56 | | -From: |
57 | | - |
58 | | -```tsx |
59 | | -import { NextContext } from 'next' |
60 | | -import { NextAppContext, DefaultAppIProps } from 'next/app' |
61 | | -import { NextDocumentContext, DefaultDocumentIProps } from 'next/document' |
62 | | -``` |
63 | | - |
64 | | -to |
65 | | - |
66 | | -```tsx |
67 | | -import { NextPageContext } from 'next' |
68 | | -import { AppContext, AppInitialProps } from 'next/app' |
69 | | -import { DocumentContext, DocumentInitialProps } from 'next/document' |
70 | | -``` |
71 | | - |
72 | | -#### The `config` key is now a special export on a page |
73 | | - |
74 | | -You may no longer export a custom variable named `config` from a page (i.e. `export { config }` / `export const config ...`). |
75 | | -This exported variable is now used to specify page-level Next.js configuration like Opt-in AMP and API Route features. |
76 | | - |
77 | | -You must rename a non-Next.js-purposed `config` export to something different. |
78 | | - |
79 | | -#### `next/dynamic` no longer renders "loading..." by default while loading |
80 | | - |
81 | | -Dynamic components will not render anything by default while loading. You can still customize this behavior by setting the `loading` property: |
82 | | - |
83 | | -```jsx |
84 | | -import dynamic from 'next/dynamic' |
85 | | - |
86 | | -const DynamicComponentWithCustomLoading = dynamic( |
87 | | - () => import('../components/hello2'), |
88 | | - { |
89 | | - loading: () => <p>Loading</p>, |
90 | | - } |
91 | | -) |
92 | | -``` |
93 | | - |
94 | | -#### `withAmp` has been removed in favor of an exported configuration object |
95 | | - |
96 | | -Next.js now has the concept of page-level configuration, so the `withAmp` higher-order component has been removed for consistency. |
97 | | - |
98 | | -This change can be **automatically migrated by running the following commands in the root of your Next.js project:** |
99 | | - |
100 | | -```bash |
101 | | -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 |
102 | | -``` |
103 | | - |
104 | | -To perform this migration by hand, or view what the codemod will produce, see below: |
105 | | - |
106 | | -**Before** |
107 | | - |
108 | | -```jsx |
109 | | -import { withAmp } from 'next/amp' |
110 | | - |
111 | | -function Home() { |
112 | | - return <h1>My AMP Page</h1> |
113 | | -} |
114 | | - |
115 | | -export default withAmp(Home) |
116 | | -// or |
117 | | -export default withAmp(Home, { hybrid: true }) |
118 | | -``` |
119 | | - |
120 | | -**After** |
121 | | - |
122 | | -```jsx |
123 | | -export default function Home() { |
124 | | - return <h1>My AMP Page</h1> |
125 | | -} |
126 | | - |
127 | | -export const config = { |
128 | | - amp: true, |
129 | | - // or |
130 | | - amp: 'hybrid', |
131 | | -} |
132 | | -``` |
133 | | - |
134 | | -#### `next export` no longer exports pages as `index.html` |
135 | | - |
136 | | -Previously, exporting `pages/about.js` would result in `out/about/index.html`. This behavior has been changed to result in `out/about.html`. |
137 | | - |
138 | | -You can revert to the previous behavior by creating a `next.config.js` with the following content: |
139 | | - |
140 | | -```js |
141 | | -// next.config.js |
142 | | -module.exports = { |
143 | | - exportTrailingSlash: true, |
144 | | -} |
145 | | -``` |
146 | | - |
147 | | -#### `./pages/api/` is treated differently |
148 | | - |
149 | | -Pages in `./pages/api/` are now considered [API Routes](https://nextjs.org/blog/next-9#api-routes). |
150 | | -Pages in this directory will no longer contain a client-side bundle. |
151 | | - |
152 | | -## Deprecated Features |
153 | | - |
154 | | -#### `next/dynamic` has deprecated loading multiple modules at once |
155 | | - |
156 | | -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`). |
157 | | - |
158 | | -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: |
159 | | - |
160 | | -**Before** |
161 | | - |
162 | | -```jsx |
163 | | -import dynamic from 'next/dynamic' |
164 | | - |
165 | | -const HelloBundle = dynamic({ |
166 | | - modules: () => { |
167 | | - const components = { |
168 | | - Hello1: () => import('../components/hello1').then(m => m.default), |
169 | | - Hello2: () => import('../components/hello2').then(m => m.default), |
170 | | - } |
171 | | - |
172 | | - return components |
173 | | - }, |
174 | | - render: (props, { Hello1, Hello2 }) => ( |
175 | | - <div> |
176 | | - <h1>{props.title}</h1> |
177 | | - <Hello1 /> |
178 | | - <Hello2 /> |
179 | | - </div> |
180 | | - ), |
181 | | -}) |
182 | | - |
183 | | -function DynamicBundle() { |
184 | | - return <HelloBundle title="Dynamic Bundle" /> |
185 | | -} |
186 | | - |
187 | | -export default DynamicBundle |
188 | | -``` |
189 | | - |
190 | | -**After** |
191 | | - |
192 | | -```jsx |
193 | | -import dynamic from 'next/dynamic' |
194 | | - |
195 | | -const Hello1 = dynamic(() => import('../components/hello1')) |
196 | | -const Hello2 = dynamic(() => import('../components/hello2')) |
197 | | - |
198 | | -function HelloBundle({ title }) { |
199 | | - return ( |
200 | | - <div> |
201 | | - <h1>{title}</h1> |
202 | | - <Hello1 /> |
203 | | - <Hello2 /> |
204 | | - </div> |
205 | | - ) |
206 | | -} |
207 | | - |
208 | | -function DynamicBundle() { |
209 | | - return <HelloBundle title="Dynamic Bundle" /> |
210 | | -} |
211 | | - |
212 | | -export default DynamicBundle |
213 | | -``` |
| 1 | +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). |
0 commit comments