1# Vue Composables
2 
3Reusable functions encapsulating stateful logic using Composition API.
4 
5## Core Rules
6 
71. **VueUse first** - check [vueuse.org](https://vueuse.org) before writing custom
82. **No async composables** - lose lifecycle context when awaited in other composables
93. **Top-level only** - never call in event handlers, conditionals, or loops
104. **readonly() exports** - protect internal state from external mutation
115. **useState() for SSR** - use Nuxt's `useState()` not global refs
12 
13## Quick Reference
14 
15| Pattern   | Example                                          |
16| --------- | ------------------------------------------------ |
17| Naming    | `useAuth`, `useCounter`, `useDebounce`           |
18| State     | `const count = ref(0)`                           |
19| Computed  | `const double = computed(() => count.value * 2)` |
20| Lifecycle | `onMounted(() => ...)`, `onUnmounted(() => ...)` |
21| Return    | `return { count, increment }`                    |
22 
23## Structure
24 
25```ts
26// composables/useCounter.ts
27import { readonly, ref } from 'vue'
28 
29export function useCounter(initialValue = 0) {
30  const count = ref(initialValue)
31 
32  function increment() { count.value++ }
33  function decrement() { count.value-- }
34  function reset() { count.value = initialValue }
35 
36  return {
37    count: readonly(count), // readonly if shouldn't be mutated
38    increment,
39    decrement,
40    reset,
41  }
42}
43```
44 
45## Naming
46 
47**Always prefix with `use`:** `useAuth`, `useLocalStorage`, `useDebounce`
48 
49**File = function:** `useAuth.ts` exports `useAuth`
50 
51## Best Practices
52 
53**Do:**
54 
55- Return object with named properties (destructuring-friendly)
56- Accept options object for configuration
57- Use `readonly()` for state that shouldn't mutate
58- Handle cleanup (`onUnmounted`, `onScopeDispose`)
59- Add JSDoc for complex functions
60 
61## Lifecycle
62 
63Hooks execute in component context:
64 
65```ts
66export function useEventListener(target: EventTarget, event: string, handler: Function) {
67  onMounted(() => target.addEventListener(event, handler))
68  onUnmounted(() => target.removeEventListener(event, handler))
69}
70```
71 
72**Watcher cleanup (Vue 3.5+):**
73 
74```ts
75import { watch, onWatcherCleanup } from 'vue'
76 
77export function usePolling(url: Ref<string>) {
78  watch(url, (newUrl) => {
79    const interval = setInterval(() => {
80      fetch(newUrl).then(/* ... */)
81    }, 1000)
82 
83    // Cleanup when watcher re-runs or stops
84    onWatcherCleanup(() => {
85      clearInterval(interval)
86    })
87  })
88}
89```
90 
91**Benefits of `onWatcherCleanup()`:**
92 
93- Cleaner than returning cleanup functions
94- Works with async watchers
95- Can be called multiple times in same watcher
96 
97## Async Pattern
98 
99```ts
100export function useAsyncData<T>(fetcher: () => Promise<T>) {
101  const data = ref<T | null>(null)
102  const error = ref<Error | null>(null)
103  const loading = ref(false)
104 
105  async function execute() {
106    loading.value = true
107    error.value = null
108    try {
109      data.value = await fetcher()
110    }
111    catch (e) {
112      error.value = e as Error
113    }
114    finally {
115      loading.value = false
116    }
117  }
118 
119  execute()
120  return { data, error, loading, refetch: execute }
121}
122```
123 
124**Data fetching:** Prefer Pinia Colada queries over custom composables.
125 
126## VueUse
127 
128> For VueUse composable reference, use the `vueuse` skill.
129 
130Check VueUse before writing custom composables - most patterns already implemented.
131 
132> **For Nuxt-specific composables** (useFetch, useRequestURL): see `nuxt` skill nuxt-composables.md
133 
134## Advanced Patterns
135 
136### Singleton Composable
137 
138Share state across all components using the same composable:
139 
140```ts
141import { createSharedComposable } from '@vueuse/core'
142 
143function useMapControlsBase() {
144  const mapInstance = ref<Map | null>(null)
145  const flyTo = (coords: [number, number]) => mapInstance.value?.flyTo(coords)
146  return { mapInstance, flyTo }
147}
148 
149export const useMapControls = createSharedComposable(useMapControlsBase)
150```
151 
152### Cancellable Fetch with AbortController
153 
154```ts
155export function useSearch() {
156  let abortController: AbortController | null = null
157 
158  watch(query, async (newQuery) => {
159    abortController?.abort()
160    abortController = new AbortController()
161 
162    try {
163      const data = await $fetch('/api/search', {
164        query: { q: newQuery },
165        signal: abortController.signal,
166      })
167    }
168    catch (e) {
169      if (e.name !== 'AbortError')
170        throw e
171    }
172  })
173}
174```
175 
176### Step-Based State Machine
177 
178```ts
179export function useSendFlow() {
180  const step = ref<'input' | 'confirm' | 'success'>('input')
181  const amount = ref('')
182 
183  const next = () => {
184    if (step.value === 'input')
185      step.value = 'confirm'
186    else if (step.value === 'confirm')
187      step.value = 'success'
188  }
189 
190  return { step, amount, next }
191}
192```
193 
194### Client-Only Guards
195 
196```ts
197export function useUserLocation() {
198  const location = ref<GeolocationPosition | null>(null)
199 
200  if (import.meta.client) {
201    navigator.geolocation.getCurrentPosition(pos => location.value = pos)
202  }
203 
204  return { location }
205}
206```
207 
208### Custom Element Composables (Vue 3.5+)
209 
210For custom element components, use built-in helpers:
211 
212```ts
213import { useHost, useShadowRoot } from 'vue'
214 
215export function useCustomElement() {
216  const host = useHost() // Host element reference
217  const shadowRoot = useShadowRoot() // Shadow DOM root
218 
219  onMounted(() => {
220    console.log('Host:', host)
221    console.log('Shadow:', shadowRoot)
222  })
223 
224  return { host, shadowRoot }
225}
226```
227 
228**Available in:**
229 
230- Components using `<script setup>` in custom elements
231- Access via `this.$host` in Options API
232 
233### Auto-Save with Debounce
234 
235```ts
236export function useAutoSave(content: Ref<string>) {
237  const hasChanges = ref(false)
238 
239  const save = useDebounceFn(async () => {
240    if (!hasChanges.value)
241      return
242    await $fetch('/api/save', { method: 'POST', body: { content: content.value } })
243    hasChanges.value = false
244  }, 1000)
245 
246  watch(content, () => {
247    hasChanges.value = true
248    save()
249  })
250 
251  return { hasChanges }
252}
253```
254 
255### Tagged Logger
256 
257```ts
258import { consola } from 'consola'
259 
260export function useSearch() {
261  const logger = consola.withTag('search')
262 
263  watch(query, (q) => {
264    logger.info('Query changed:', q)
265  })
266}
267```
268 
269## Reactivity Gotchas
270 
271### Ref Unwrapping in Reactive
272 
273Refs auto-unwrap in `reactive()` objects but **NOT** in arrays, Maps, or Sets:
274 
275```ts
276// ✅ Object - auto unwraps
277const state = reactive({ count: ref(0) })
278state.count++ // No .value needed
279 
280// ❌ Array - NO unwrapping
281const arr = reactive([ref(1)])
282arr[0].value // Need .value!
283 
284// ❌ Map/Set - NO unwrapping
285const map = reactive(new Map([['key', ref(1)]]))
286map.get('key').value // Need .value!
287```
288 
289### watchEffect Conditional Tracking
290 
291Dependencies inside conditional branches are **not tracked** when condition is false:
292 
293```ts
294// ❌ Wrong - dep not tracked when condition false
295watchEffect(() => {
296  if (condition.value) {
297    console.log(dep.value) // Only tracked when condition=true
298  }
299})
300 
301// ✅ Correct - use explicit watch for conditional deps
302watch([condition, dep], ([cond, d]) => {
303  if (cond) console.log(d)
304})
305```
306 
307### Cleanup Patterns
308 
309**For keep-alive components** - use `onDeactivated`:
310 
311```ts
312export function usePolling() {
313  let interval: NodeJS.Timeout
314 
315  onMounted(() => { interval = setInterval(poll, 5000) })
316  onUnmounted(() => clearInterval(interval))
317  onDeactivated(() => clearInterval(interval)) // Pause when deactivated
318  onActivated(() => { interval = setInterval(poll, 5000) }) // Resume
319}
320```
321 
322**For scope-aware cleanup** - use `tryOnScopeDispose` from VueUse:
323 
324```ts
325import { tryOnScopeDispose } from '@vueuse/core'
326 
327export function useEventSource(url: string) {
328  const source = new EventSource(url)
329 
330  // Cleans up when effect scope disposes (component unmount, watcher stop)
331  tryOnScopeDispose(() => source.close())
332 
333  return { source }
334}
335```
336 
337## Common Mistakes
338 
339**Not using `readonly()` for internal state:**
340 
341```ts
342// ❌ Wrong - exposes mutable ref
343return { count }
344 
345// ✅ Correct - prevents external mutation
346return { count: readonly(count) }
347```
348 
349**Missing cleanup:**
350 
351```ts
352// ❌ Wrong - listener never removed
353onMounted(() => target.addEventListener('click', handler))
354 
355// ✅ Correct - cleanup on unmount
356onMounted(() => target.addEventListener('click', handler))
357onUnmounted(() => target.removeEventListener('click', handler))
358```
359