From 357bb7f271bf7bfd6f013825c3f4ebbcb05d27c0 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Wed, 27 Oct 2021 13:46:52 +0100
Subject: [PATCH] docs: advice on `async setup()` with multiple awaits (#1517)

---
 .../content/3.docs/1.usage/1.data-fetching.md | 34 ++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/docs/content/3.docs/1.usage/1.data-fetching.md b/docs/content/3.docs/1.usage/1.data-fetching.md
index e9ed2be9d7..325096ba04 100644
--- a/docs/content/3.docs/1.usage/1.data-fetching.md
+++ b/docs/content/3.docs/1.usage/1.data-fetching.md
@@ -82,7 +82,9 @@ const { data } = await useFetch('/api/count')
 
 The data returned by `useAsyncData` will be stored inside the page payload. This means that every key returned that is not used in your component will be added to the payload.
 
-**We strongly recommend to only select the keys that you will use in your component.**
+::alert{icon=👉}
+**We strongly recommend you only select the keys that you will use in your component.**
+::
 
 Imagine that `/api/mountains/everest` returns the following object:
 
@@ -112,3 +114,33 @@ const { data: mountain } = await useFetch('/api/mountains/everest', { pick: ['ti
   <p>{{ mountain.description }}</p>
 </template>
 ```
+
+### Using async setup
+
+If you are using `async setup()`, the current component instance will be lost after the first `await`. (This is a Vue 3 limitation.) If you want to use multiple async operations, such as multiple calls to `useFetch`, you will need to use `<script setup>` or await them together at the end of setup.
+
+::alert{icon=👉}
+Using `<script setup>` is recommended, as it removes the limitation of using top-level await. [Read more](https://v3.vuejs.org/api/sfc-script-setup.html#top-level-await)
+::
+
+```vue
+<script>
+export default defineComponent({
+  async setup() {
+    const [{ data: organization }, { data: repos }] = await Promise.all([
+      useFetch(`https://api.github.com/orgs/nuxtjs`),
+      useFetch(`https://api.github.com/orgs/nuxtjs/repos`)
+    ])
+
+    return {
+      organization,
+      repos
+    }
+  }
+})
+
+<template>
+  <h1>{{ mountain.title }}</h1>
+  <p>{{ mountain.description }}</p>
+</template>
+```