1---
2title: Provide Must Be Called Synchronously During Setup
3impact: HIGH
4impactDescription: Calling provide() asynchronously or conditionally may fail silently or cause inconsistent injection behavior
5type: gotcha
6tags: [vue3, provide-inject, composition-api, async, setup]
7---
8 
9# Provide Must Be Called Synchronously During Setup
10 
11**Impact: HIGH** - The `provide()` function must be called synchronously during the component's `setup()` phase. Calling it asynchronously (inside callbacks, promises, or after await) will fail silently, and descendant components will not receive the provided value.
12 
13## Task Checklist
14 
15- [ ] Always call `provide()` at the top level of `setup()` or `<script setup>`
16- [ ] Never call `provide()` inside async callbacks or after await statements
17- [ ] For async data, provide a ref first, then update its value later
18- [ ] Use immediate `provide()` with reactive containers for dynamic data
19 
20## The Gotcha: Async Provide Fails Silently
21 
22**Wrong - Provide after async operation:**
23```vue
24<script setup>
25import { provide } from 'vue'
26 
27// WRONG: provide() called after await - will NOT work
28onMounted(async () => {
29  const userData = await fetchUser()
30  provide('user', userData) // Silent failure!
31})
32</script>
33```
34 
35**Wrong - Provide inside callback:**
36```vue
37<script setup>
38import { provide } from 'vue'
39 
40// WRONG: provide() inside callback - will NOT work
41setTimeout(() => {
42  provide('config', { theme: 'dark' }) // Silent failure!
43}, 0)
44</script>
45```
46 
47**Wrong - Provide after await in setup:**
48```vue
49<script setup>
50import { provide } from 'vue'
51 
52const response = await fetch('/api/config')
53const config = await response.json()
54 
55// WRONG: This is after an await, setup context may be lost
56provide('config', config) // May not work reliably
57</script>
58```
59 
60## Solution: Provide Synchronously, Update Async
61 
62**Correct - Provide ref immediately, update later:**
63```vue
64<script setup>
65import { provide, ref, onMounted } from 'vue'
66 
67// Provide immediately with initial value
68const user = ref(null)
69const isLoading = ref(true)
70const error = ref(null)
71 
72provide('userState', {
73  user,
74  isLoading,
75  error
76})
77 
78// Update the ref values asynchronously
79onMounted(async () => {
80  try {
81    const userData = await fetchUser()
82    user.value = userData
83  } catch (e) {
84    error.value = e
85  } finally {
86    isLoading.value = false
87  }
88})
89</script>
90```
91 
92```vue
93<!-- Consumer component -->
94<script setup>
95import { inject } from 'vue'
96 
97const { user, isLoading, error } = inject('userState')
98</script>
99 
100<template>
101  <div v-if="isLoading">Loading...</div>
102  <div v-else-if="error">Error: {{ error.message }}</div>
103  <div v-else>Welcome, {{ user?.name }}</div>
104</template>
105```
106 
107## Pattern: Async Data Provider
108 
109Create a reusable pattern for async-provided data:
110 
111```vue
112<!-- AsyncDataProvider.vue -->
113<script setup>
114import { provide, ref, onMounted, watch } from 'vue'
115 
116const props = defineProps({
117  fetchFn: {
118    type: Function,
119    required: true
120  },
121  provideKey: {
122    type: [String, Symbol],
123    required: true
124  },
125  immediate: {
126    type: Boolean,
127    default: true
128  }
129})
130 
131const data = ref(null)
132const isLoading = ref(false)
133const error = ref(null)
134 
135async function load() {
136  isLoading.value = true
137  error.value = null
138 
139  try {
140    data.value = await props.fetchFn()
141  } catch (e) {
142    error.value = e
143  } finally {
144    isLoading.value = false
145  }
146}
147 
148// Provide synchronously
149provide(props.provideKey, {
150  data,
151  isLoading,
152  error,
153  reload: load
154})
155 
156// Fetch asynchronously
157if (props.immediate) {
158  onMounted(load)
159}
160</script>
161 
162<template>
163  <slot />
164</template>
165```
166 
167Usage:
168 
169```vue
170<template>
171  <AsyncDataProvider
172    :fetch-fn="() => api.getUser(userId)"
173    provide-key="userData"
174  >
175    <UserProfile />
176  </AsyncDataProvider>
177</template>
178```
179 
180## Why This Happens
181 
182Vue's `provide()` relies on the current component instance context, which is only available synchronously during setup. After setup completes:
183 
1841. The setup context is cleared
1852. `provide()` can't find the current instance
1863. The call fails silently (no error thrown)
187 
188## Checking for Setup Context
189 
190You can verify if setup context is available:
191 
192```js
193import { getCurrentInstance } from 'vue'
194 
195function debugProvide(key, value) {
196  const instance = getCurrentInstance()
197 
198  if (!instance) {
199    console.error(
200      `provide() called outside setup context. ` +
201      `Key: ${String(key)}. This will fail silently.`
202    )
203    return
204  }
205 
206  provide(key, value)
207}
208```
209 
210## App-Level Provide (Exception)
211 
212`app.provide()` can be called anytime during app initialization:
213 
214```js
215// main.js
216import { createApp } from 'vue'
217import App from './App.vue'
218 
219const app = createApp(App)
220 
221// This works - app-level provide
222app.provide('appConfig', { version: '1.0.0' })
223 
224// Even async is OK at app level before mount
225fetchConfig().then(config => {
226  app.provide('apiConfig', config)
227  app.mount('#app')
228})
229```
230 
231But once the app is mounted, `app.provide()` should not be called.
232 
233## Reference
234- [Vue.js Composition API - provide()](https://vuejs.org/api/composition-api-dependency-injection.html#provide)
235- [Vue.js Provide/Inject Guide](https://vuejs.org/guide/components/provide-inject.html)
236