1---
2title: Avoid Hidden Side Effects in Composables
3impact: HIGH
4impactDescription: Side effects hidden in composables make debugging difficult and create implicit coupling between components
5type: best-practice
6tags: [vue3, composables, composition-api, side-effects, provide-inject, global-state]
7---
8 
9# Avoid Hidden Side Effects in Composables
10 
11**Impact: HIGH** - Composables should encapsulate stateful logic, not hide side effects that affect things outside their scope. Hidden side effects like modifying global state, using provide/inject internally, or manipulating the DOM directly make composables unpredictable and hard to debug.
12 
13When a composable has unexpected side effects, consumers can't reason about what calling it will do. This leads to bugs that are difficult to trace and composables that can't be safely reused.
14 
15## Task Checklist
16 
17- [ ] Avoid using provide/inject inside composables (make dependencies explicit)
18- [ ] Don't modify Pinia/Vuex store state internally (accept store as parameter instead)
19- [ ] Don't manipulate DOM directly (use template refs passed as arguments)
20- [ ] Document any unavoidable side effects clearly
21- [ ] Keep composables focused on returning reactive state and methods
22 
23**Incorrect:**
24```javascript
25// WRONG: Hidden provide/inject dependency
26export function useTheme() {
27  // Consumer has no idea this depends on a provided theme
28  const theme = inject('theme')  // What if nothing provides this?
29 
30  const isDark = computed(() => theme?.mode === 'dark')
31  return { isDark }
32}
33 
34// WRONG: Modifying global store internally
35import { useUserStore } from '@/stores/user'
36 
37export function useLogin() {
38  const userStore = useUserStore()
39 
40  async function login(credentials) {
41    const user = await api.login(credentials)
42    // Hidden side effect: modifying global state
43    userStore.setUser(user)
44    userStore.setToken(user.token)
45    // Consumer doesn't know the store was modified!
46  }
47 
48  return { login }
49}
50 
51// WRONG: Hidden DOM manipulation
52export function useFocusTrap() {
53  onMounted(() => {
54    // Which element? Consumer has no control
55    document.querySelector('.modal')?.focus()
56  })
57}
58 
59// WRONG: Hidden provide that affects descendants
60export function useFormContext() {
61  const form = reactive({ values: {}, errors: {} })
62  // Components calling this have no idea it provides something
63  provide('form-context', form)
64  return form
65}
66```
67 
68**Correct:**
69```javascript
70// CORRECT: Explicit dependency injection
71export function useTheme(injectedTheme) {
72  // If no theme passed, consumer must handle it
73  const theme = injectedTheme ?? { mode: 'light' }
74 
75  const isDark = computed(() => theme.mode === 'dark')
76  return { isDark }
77}
78 
79// Usage - dependency is explicit
80const theme = inject('theme', { mode: 'light' })
81const { isDark } = useTheme(theme)
82 
83// CORRECT: Return actions, let consumer decide when to call them
84export function useLogin() {
85  const user = ref(null)
86  const token = ref(null)
87  const isLoading = ref(false)
88  const error = ref(null)
89 
90  async function login(credentials) {
91    isLoading.value = true
92    error.value = null
93    try {
94      const response = await api.login(credentials)
95      user.value = response.user
96      token.value = response.token
97      return response
98    } catch (e) {
99      error.value = e
100      throw e
101    } finally {
102      isLoading.value = false
103    }
104  }
105 
106  return { user, token, isLoading, error, login }
107}
108 
109// Consumer decides what to do with the result
110const { user, token, login } = useLogin()
111const userStore = useUserStore()
112 
113async function handleLogin(credentials) {
114  await login(credentials)
115  // Consumer explicitly updates the store
116  userStore.setUser(user.value)
117  userStore.setToken(token.value)
118}
119 
120// CORRECT: Accept element as parameter
121export function useFocusTrap(targetRef) {
122  onMounted(() => {
123    targetRef.value?.focus()
124  })
125 
126  onUnmounted(() => {
127    // Cleanup focus trap
128  })
129}
130 
131// Usage - consumer controls which element
132const modalRef = ref(null)
133useFocusTrap(modalRef)
134 
135// CORRECT: Separate composable from provider
136export function useFormContext() {
137  const form = reactive({ values: {}, errors: {} })
138  return form
139}
140 
141// In parent component - explicit provide
142const form = useFormContext()
143provide('form-context', form)
144```
145 
146## Acceptable Side Effects (With Documentation)
147 
148Some side effects are acceptable when they're the core purpose of the composable:
149 
150```javascript
151/**
152 * Tracks mouse position globally.
153 *
154 * SIDE EFFECTS:
155 * - Adds 'mousemove' event listener to window (cleaned up on unmount)
156 *
157 * @returns {Object} Mouse coordinates { x, y }
158 */
159export function useMouse() {
160  const x = ref(0)
161  const y = ref(0)
162 
163  // This side effect is the whole point of the composable
164  // and is properly cleaned up
165  onMounted(() => window.addEventListener('mousemove', update))
166  onUnmounted(() => window.removeEventListener('mousemove', update))
167 
168  function update(event) {
169    x.value = event.pageX
170    y.value = event.pageY
171  }
172 
173  return { x, y }
174}
175```
176 
177## Pattern: Dependency Injection for Flexibility
178 
179```javascript
180// Composable accepts its dependencies
181export function useDataFetcher(apiClient, cache = null) {
182  const data = ref(null)
183 
184  async function fetch(url) {
185    if (cache) {
186      const cached = cache.get(url)
187      if (cached) {
188        data.value = cached
189        return
190      }
191    }
192 
193    data.value = await apiClient.get(url)
194    cache?.set(url, data.value)
195  }
196 
197  return { data, fetch }
198}
199 
200// Usage - dependencies are explicit and testable
201const apiClient = inject('apiClient')
202const cache = inject('cache', null)
203const { data, fetch } = useDataFetcher(apiClient, cache)
204```
205 
206## Reference
207- [Vue.js Composables](https://vuejs.org/guide/reusability/composables.html)
208- [Common Mistakes Creating Composition Functions](https://www.telerik.com/blogs/common-mistakes-creating-composition-functions-vue)
209