1---
2title: Top-Level await in script setup Preserves Component Context
3impact: HIGH
4impactDescription: Misunderstanding async context causes lifecycle hooks and watchers to silently fail
5type: gotcha
6tags: [vue3, composition-api, script-setup, async, await, suspense]
7---
8 
9# Top-Level await in script setup Preserves Component Context
10 
11**Impact: HIGH** - In `<script setup>`, top-level `await` statements preserve component context (allowing lifecycle hooks and watchers after `await`), but this is a special case. Nested async functions or callbacks lose context, causing lifecycle hooks to silently fail.
12 
13Vue's compiler automatically injects context restoration after each top-level await in `<script setup>`. This doesn't apply to `setup()` function or nested async contexts.
14 
15## Task Checklist
16 
17- [ ] Understand that top-level await in `<script setup>` is specially handled
18- [ ] Never register lifecycle hooks in nested async functions
19- [ ] Use `<Suspense>` when using async `<script setup>` components
20- [ ] In regular `setup()`, never use await before lifecycle hook registration
21- [ ] Register hooks synchronously, then do async work inside them
22 
23**Top-Level await Works (script setup only):**
24```vue
25<script setup>
26import { ref, onMounted, watch } from 'vue'
27 
28// This is TOP-LEVEL await - Vue compiler preserves context
29const config = await fetchConfig()  // OK!
30 
31// These hooks work because Vue restored context
32onMounted(() => {
33  console.log('This will run!')  // Works
34})
35 
36watch(someRef, () => {
37  console.log('This will track!')  // Works
38})
39 
40// Another top-level await - still OK
41const data = await fetchData(config.apiUrl)  // OK!
42 
43// Still works after multiple awaits
44onMounted(() => {
45  console.log('This also runs!')  // Works
46})
47</script>
48 
49<!-- IMPORTANT: Parent must use Suspense -->
50<template>
51  <Suspense>
52    <AsyncComponent />
53  </Suspense>
54</template>
55```
56 
57**Nested Async Breaks Context:**
58```vue
59<script setup>
60import { ref, onMounted, watch } from 'vue'
61 
62// WRONG: Nested async function - context lost after await
63async function initializeData() {
64  const config = await fetchConfig()
65 
66  // BUG: This hook will NOT be registered!
67  // We're no longer in the synchronous setup context
68  onMounted(() => {
69    console.log('This will NEVER run!')  // Silent failure
70  })
71 
72  // BUG: This watcher won't auto-dispose on unmount
73  watch(someRef, () => {
74    console.log('Memory leak - not cleaned up!')
75  })
76}
77 
78// Calling the async function
79initializeData()  // Hooks inside won't work!
80 
81// WRONG: Callbacks also lose context
82setTimeout(async () => {
83  await delay(100)
84  onMounted(() => {
85    console.log('Never runs!')  // Silent failure
86  })
87}, 0)
88</script>
89```
90 
91**Correct Patterns:**
92```vue
93<script setup>
94import { ref, onMounted, watch } from 'vue'
95 
96const data = ref(null)
97const config = ref(null)
98 
99// CORRECT: Register hooks synchronously FIRST
100onMounted(async () => {
101  // Then do async work INSIDE the hook
102  config.value = await fetchConfig()
103  data.value = await fetchData(config.value.apiUrl)
104})
105 
106// CORRECT: Watchers registered synchronously
107watch(config, async (newConfig) => {
108  if (newConfig) {
109    data.value = await fetchData(newConfig.apiUrl)
110  }
111})
112 
113// Or use top-level await for initial data
114const initialConfig = await fetchConfig()  // OK - top level
115config.value = initialConfig
116 
117onMounted(() => {
118  console.log('Works!')  // Context preserved by compiler
119})
120</script>
121```
122 
123**setup() Function (Not script setup):**
124```javascript
125// In regular setup(), await ALWAYS breaks context
126export default {
127  async setup() {
128    const data = ref(null)
129 
130    // WRONG: Hooks after await won't register
131    const config = await fetchConfig()
132 
133    onMounted(() => {
134      console.log('Never runs!')  // Silent failure!
135    })
136 
137    return { data }
138  }
139}
140 
141// CORRECT: Register hooks before any await
142export default {
143  async setup() {
144    const data = ref(null)
145 
146    // Register hooks FIRST (synchronous)
147    onMounted(async () => {
148      const config = await fetchConfig()
149      data.value = await fetchData(config)
150    })
151 
152    // Now you can await if needed
153    // But hooks must be registered before this point
154 
155    return { data }
156  }
157}
158```
159 
160## Why This Happens
161 
162```javascript
163// Vue tracks the "current component instance" during setup
164// This is like a global variable that gets set and cleared
165 
166// During synchronous setup:
167function setup() {
168  currentInstance = this  // Vue sets this
169 
170  onMounted(cb)  // Uses currentInstance to register
171 
172  // After await, JavaScript resumes in a microtask
173  await something()
174 
175  // currentInstance is now null or different!
176  onMounted(cb)  // Can't find the instance - silently fails
177}
178 
179// <script setup> compiler adds restoration:
180// After each await, it injects: setCurrentInstance(savedInstance)
181```
182 
183## Suspense Requirement
184 
185```vue
186<!-- When using async script setup, parent needs Suspense -->
187<template>
188  <Suspense>
189    <!-- Async component with top-level await -->
190    <AsyncChild />
191 
192    <!-- Optional: Loading state -->
193    <template #fallback>
194      <LoadingSpinner />
195    </template>
196  </Suspense>
197</template>
198```
199 
200## Reference
201- [Composition API FAQ - Async Setup](https://vuejs.org/guide/extras/composition-api-faq.html)
202- [Composables - Async Without Await](https://antfu.me/posts/async-with-composition-api)
203- [Suspense](https://vuejs.org/guide/built-ins/suspense.html)
204