1---
2title: defineExpose Must Be Called Before Any Await
3impact: HIGH
4impactDescription: Properties exposed after await are inaccessible to parent component refs
5type: gotcha
6tags: [vue3, script-setup, defineExpose, async, component-refs]
7---
8 
9# defineExpose Must Be Called Before Any Await
10 
11**Impact: HIGH** - In `<script setup>`, if you call `defineExpose()` after an `await` statement, the exposed properties will NOT be accessible to parent components using template refs. This is a subtle async timing issue that causes silent failures.
12 
13The compiler transforms top-level await, and code after await runs in a different execution context where defineExpose cannot properly register with the component instance.
14 
15## Task Checklist
16 
17- [ ] Always call defineExpose() at the top of script setup, before any await
18- [ ] If async data is needed in exposed methods, fetch it separately
19- [ ] Structure code so expose declarations come first
20- [ ] Test parent ref access when using async setup
21 
22**Incorrect:**
23```vue
24<!-- ChildComponent.vue -->
25<script setup>
26import { ref } from 'vue'
27 
28const data = ref(null)
29const count = ref(0)
30 
31function increment() {
32  count.value++
33}
34 
35// WRONG: await before defineExpose
36const response = await fetch('/api/data')
37data.value = await response.json()
38 
39// BROKEN: This won't work - called after await!
40defineExpose({
41  count,
42  increment,
43  data
44})
45</script>
46 
47<template>
48  <div>{{ data }}</div>
49</template>
50```
51 
52```vue
53<!-- ParentComponent.vue -->
54<script setup>
55import { ref, onMounted } from 'vue'
56import ChildComponent from './ChildComponent.vue'
57 
58const childRef = ref(null)
59 
60onMounted(() => {
61  // FAILS: All exposed properties are undefined!
62  console.log(childRef.value.count) // undefined
63  childRef.value.increment() // TypeError
64})
65</script>
66 
67<template>
68  <Suspense>
69    <ChildComponent ref="childRef" />
70  </Suspense>
71</template>
72```
73 
74**Correct:**
75```vue
76<!-- ChildComponent.vue -->
77<script setup>
78import { ref } from 'vue'
79 
80const data = ref(null)
81const count = ref(0)
82 
83function increment() {
84  count.value++
85}
86 
87// CORRECT: defineExpose BEFORE any await
88defineExpose({
89  count,
90  increment,
91  data
92})
93 
94// Now safe to use await
95const response = await fetch('/api/data')
96data.value = await response.json()
97</script>
98 
99<template>
100  <div>{{ data }}</div>
101</template>
102```
103 
104```vue
105<!-- Alternative: Separate async logic from expose -->
106<script setup>
107import { ref, onMounted } from 'vue'
108 
109const data = ref(null)
110const loading = ref(true)
111 
112function getData() {
113  return data.value
114}
115 
116async function refreshData() {
117  loading.value = true
118  const response = await fetch('/api/data')
119  data.value = await response.json()
120  loading.value = false
121}
122 
123// CORRECT: No await at top level - defineExpose always works
124defineExpose({
125  data,
126  getData,
127  refreshData,
128  loading
129})
130 
131// Trigger async load in lifecycle hook instead
132onMounted(() => {
133  refreshData()
134})
135</script>
136 
137<template>
138  <div v-if="loading">Loading...</div>
139  <div v-else>{{ data }}</div>
140</template>
141```
142 
143```vue
144<!-- If you must use top-level await, define expose first -->
145<script setup>
146import { ref } from 'vue'
147 
148const user = ref(null)
149const posts = ref([])
150 
151// CORRECT: All expose calls come first
152defineExpose({
153  user,
154  posts,
155  refresh: () => loadData()
156})
157 
158// Now safe to await
159async function loadData() {
160  const [userRes, postsRes] = await Promise.all([
161    fetch('/api/user'),
162    fetch('/api/posts')
163  ])
164  user.value = await userRes.json()
165  posts.value = await postsRes.json()
166}
167 
168// Top-level await after defineExpose is safe
169await loadData()
170</script>
171```
172 
173## Why This Happens
174 
175Vue's compiler transforms `<script setup>` with top-level await into an async setup function. The component instance context is only available synchronously before the first await. After await, the execution resumes outside that context, making defineExpose ineffective.
176 
177```javascript
178// What the compiler roughly generates:
179async setup() {
180  const count = ref(0)
181 
182  // Context available here
183  await fetch(...)  // Suspends execution
184 
185  // Context lost after resuming
186  defineExpose({ count }) // Too late!
187}
188```
189 
190## Reference
191- [Vue.js Script Setup - defineExpose](https://vuejs.org/api/sfc-script-setup.html#defineexpose)
192- [Vue.js Async Components](https://vuejs.org/guide/components/async.html)
193