From acc5af61ae893f958850365384dd81e64ea84289 Mon Sep 17 00:00:00 2001
From: Ben Hong <ben@bencodezen.io>
Date: Mon, 6 Jul 2020 23:39:07 -0400
Subject: [PATCH] docs (#137): add async component to migration guide

---
 src/.vuepress/config.js                 |  2 +-
 src/guide/migration/async-components.md | 88 +++++++++++++++++++++++++
 2 files changed, 89 insertions(+), 1 deletion(-)
 create mode 100644 src/guide/migration/async-components.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index 942e852a29..239f503b06 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -75,7 +75,7 @@ const sidebar = {
     {
       title: 'Migration to Vue 3',
       collapsable: true,
-      children: ['migration']
+      children: ['migration', 'migration/async-components']
     },
     {
       title: 'Contribute to the Docs',
diff --git a/src/guide/migration/async-components.md b/src/guide/migration/async-components.md
new file mode 100644
index 0000000000..6a6b6fa4a8
--- /dev/null
+++ b/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)