1---
2title: Call Composables Only in Setup Context Synchronously
3impact: HIGH
4impactDescription: Composables called outside setup context or asynchronously fail to register lifecycle hooks and may cause memory leaks
5type: gotcha
6tags: [vue3, composables, composition-api, setup, async, lifecycle]
7---
8 
9# Call Composables Only in Setup Context Synchronously
10 
11**Impact: HIGH** - Composables must be called synchronously within `<script setup>`, the `setup()` function, or lifecycle hooks. Calling composables asynchronously (after await), in callbacks, or outside component context prevents Vue from associating lifecycle hooks with the component instance, causing silent failures.
12 
13This is critical because composables often register `onMounted` and `onUnmounted` hooks internally. If called in the wrong context, these hooks are never registered, leading to uninitialized state or memory leaks.
14 
15## Task Checklist
16 
17- [ ] Call all composables at the top level of `<script setup>` or `setup()`
18- [ ] Never call composables inside async callbacks, setTimeout, or Promise.then
19- [ ] Never call composables conditionally (if/else) - call unconditionally and handle the condition inside
20- [ ] Never call composables inside loops - restructure to call once with array data
21- [ ] Exception: Composables CAN be called in lifecycle hooks like `onMounted`
22 
23**Incorrect:**
24```vue
25<script setup>
26import { useFetch } from './composables/useFetch'
27import { useAuth } from './composables/useAuth'
28 
29// WRONG: Composable called after await
30const config = await loadConfig()
31const { data } = useFetch(config.apiUrl)  // Lifecycle hooks won't register!
32 
33// WRONG: Composable called conditionally
34if (someCondition) {
35  const { user } = useAuth()  // Inconsistent hook registration!
36}
37 
38// WRONG: Composable called in callback
39setTimeout(() => {
40  const { data } = useFetch('/api/delayed')  // No component context!
41}, 1000)
42 
43// WRONG: Composable called in loop
44for (const url of urls) {
45  const { data } = useFetch(url)  // Creates multiple instances incorrectly
46}
47</script>
48```
49 
50**Correct:**
51```vue
52<script setup>
53import { ref, onMounted } from 'vue'
54import { useFetch } from './composables/useFetch'
55import { useAuth } from './composables/useAuth'
56 
57// CORRECT: Call composables synchronously at top level
58const { user, isAuthenticated } = useAuth()
59const apiUrl = ref('/api/default')
60const { data, execute } = useFetch(apiUrl)
61 
62// Handle async config loading differently
63onMounted(async () => {
64  const config = await loadConfig()
65  apiUrl.value = config.apiUrl  // Update the ref, composable reacts
66})
67 
68// CORRECT: Handle condition inside, not outside
69const showUserData = computed(() => isAuthenticated.value && someCondition)
70 
71// CORRECT: For multiple URLs, use a different pattern
72const urls = ref(['/api/a', '/api/b', '/api/c'])
73const results = ref([])
74 
75// Either fetch in onMounted or use a composable designed for arrays
76onMounted(async () => {
77  results.value = await Promise.all(urls.value.map(url => fetch(url)))
78})
79</script>
80```
81 
82## Exception: Calling in Lifecycle Hooks
83 
84Composables CAN be called inside lifecycle hooks because Vue maintains the component context:
85 
86```vue
87<script setup>
88import { onMounted } from 'vue'
89import { useEventListener } from '@vueuse/core'
90 
91// CORRECT: Called in lifecycle hook - component context is available
92onMounted(() => {
93  // This works because we're still in the component's execution context
94  useEventListener(document, 'visibilitychange', handleVisibility)
95})
96</script>
97```
98 
99## Special Case: Async Setup in `<script setup>`
100 
101Top-level await in `<script setup>` is special - Vue's compiler automatically preserves context:
102 
103```vue
104<script setup>
105import { useFetch } from './composables/useFetch'
106 
107// CORRECT: Top-level await in <script setup> preserves context
108// Vue compiler handles this specially
109const config = await loadConfig()
110const { data } = useFetch(config.apiUrl)  // This works!
111 
112// But nested awaits still break context:
113async function initLater() {
114  await delay(1000)
115  const { data } = useFetch('/api/late')  // WRONG: This won't work!
116}
117</script>
118```
119 
120## Why This Matters
121 
122When you call a composable, Vue needs to know which component instance to associate it with. This association happens through an internal "current instance" that's only set during synchronous setup execution.
123 
124```javascript
125// Inside a composable
126export function useFetch(url) {
127  const data = ref(null)
128 
129  // These need the current component instance!
130  onMounted(() => { /* ... */ })
131  onUnmounted(() => { /* cleanup */ })
132 
133  // If called outside setup context, Vue can't find the instance
134  // and these hooks are silently ignored
135  return { data }
136}
137```
138 
139## Reference
140- [Vue.js Composables - Usage Restrictions](https://vuejs.org/guide/reusability/composables.html#usage-restrictions)
141- [Vue.js Composition API - Setup Context](https://vuejs.org/api/composition-api-setup.html)
142