pulse-libs/skills/vue/composables.md

Composables Design

Composable Philosophy

• Composables are functions that encapsulate stateful logic
• Name with use prefix—useMouse, useAuth, useFetch
• Return refs/reactive, not plain values—caller needs reactivity
• Composables are like custom hooks in React

Basic Structure

export function useCounter(initial = 0) {
  const count = ref(initial)
  const increment = () => count.value++
  const decrement = () => count.value--
  return { count, increment, decrement }
}

Input Flexibility

• Accept ref OR plain value as input—support both use cases
• toValue() (3.3+) unwraps ref or returns value—flexible API
• For reactive objects, consider accepting getter function
• Document what inputs are accepted

Return Value Patterns

• Return object with named properties—allows destructuring what's needed
• Return refs, not reactive—easier to destructure
• Return methods along with state—complete API
• Consider returning readonly for state—prevent external mutation

Lifecycle in Composables

• onMounted, onUnmounted work inside composables—attached to calling component
• Cleanup with onUnmounted—unsubscribe, clear timers
• Composable must be called synchronously in setup—not in callbacks
• Multiple components using same composable = separate instances

Side Effects

• Start effects in composable—they run when component mounts
• Clean up in onUnmounted—or use cleanup function in watchEffect
• Consider onScopeDispose for effect scope cleanup
• Return stop functions for manual control

Async Composables

• Return reactive state that updates when async completes
• Include loading and error states—{data, isLoading, error}
• Consider useFetch pattern from VueUse
• For SSR, handle hydration mismatch

Composition Patterns

• Composables can use other composables—build on abstractions
• Avoid deep nesting—keep composables focused
• Share types between composables—consistent API
• Consider extracting to separate packages—if truly reusable

VueUse Reference

• Rich composable library—200+ utilities
• Study patterns in VueUse—excellent examples
• Don't reinvent—check if VueUse has it
• Extend VueUse composables rather than replacing