docs (#137): add async component to migration guide

src/.vuepress/config.js

@@ -48,7 +48,11 @@ const sidebar = {
  children: [
  {
  title: 'Reactivity',
- children: ['/guide/reactivity', '/guide/reactivity-fundamentals', '/guide/reactivity-computed-watchers']
+ children: [
+ '/guide/reactivity',
+ '/guide/reactivity-fundamentals',
+ '/guide/reactivity-computed-watchers'
+ ]
  },
  {
  title: 'Composition API',
@@ -83,9 +87,11 @@ const sidebar = {
  title: 'Migration to Vue 3',
  collapsable: true,
  children: [
+ 'migration',
  'migration/global-api',
  'migration/treeshaking',
- 'migration/functional-components'
+ 'migration/functional-components',
+ 'migration/async-components'
  ]
  },
  {

src/guide/migration/async-components.md

@@ -0,0 +1,88 @@
+# Async Components
+
+## Overview
+
+Here is a high level overview of what has changed:
+
+- New `defineAsyncComponent` helper method that explicitly defines async components
+- `component` option renamed to `loader`
+- Loader function does not inherently receive `resolve` and `reject` arguments and must return a Promise
+
+For a more in-depth explanation, read on!
+
+## Introduction
+
+Previously, async components were created by simply defining a component as a function that returned a promise, such as:
+
+```js
+const asyncPage = () => import('./NextPage.vue')
+```
+
+Or, for the more advanced component syntax with options:
+
+```js
+const asyncPage = {
+ component: () => import('./NextPage.vue'),
+ delay: 200,
+ timeout: 3000,
+ error: ErrorComponent,
+ loading: LoadingComponent
+}
+```
+
+## Current Syntax
+
+Now, in Vue 3, since functional components are defined as pure functions, async components definitions need to be explicitly defined by wrapping it in a new `defineAsyncComponent` helper:
+
+```js
+import { defineAsyncComponent } from 'vue'
+import ErrorComponent from './components/ErrorComponent.vue'
+import LoadingComponent from './components/LoadingComponent.vue'
+
+// Async component without options
+const asyncPage = defineAsyncComponent(() => import('./NextPage.vue'))
+
+// Async component with options
+const asyncPageWithOptions = defineAsyncComponent({
+ loader: () => import('./NextPage.vue'),
+ delay: 200,
+ timeout: 3000,
+ errorComponent: ErrorComponent,
+ loadingComponent: LoadingComponent
+})
+```
+
+Another change that has been made from v2 is that the `component` option is now renamed to `loader` in order to accurately communicate that a component definition cannot be provided directly.
+
+```js{4}
+import { defineAsyncComponent } from 'vue'
+
+const asyncPageWithOptions = defineAsyncComponent({
+ loader: () => import('./NextPAge.vue'),
+ delay: 200,
+ timeout: 3000,
+ error: ErrorComponent,
+ loading: LoadingComponent
+})
+```
+
+In addition, unlike 2.x, the loader function no longer receives the `resolve` and `reject` arguments and must always return a Promise.
+
+```js
+// 2.x version
+const oldAsyncComponent = (resolve, reject) => {
+ /* ... */
+}
+
+// 3.x version
+const asyncComponent = defineAsyncComponent(
+ () =>
+ new Promise((resolve, reject) => {
+ /* ... */
+ })
+)
+```
+
+For more information on the usage of async components, see:
+
+- [Guide: Dynamic & Async Components](/guide/component-dynamic-async.html#dynamic-components-with-keep-alive)