1---
2title: Composable Organization Patterns
3impact: MEDIUM
4impactDescription: Well-structured composables improve maintainability, reusability, and update performance
5type: best-practice
6tags: [vue3, composables, composition-api, code-organization, api-design, readonly, utilities]
7---
8 
9# Composable Organization Patterns
10 
11**Impact: MEDIUM** - Treat composables as reusable, stateful building blocks and keep their code organized by feature concern. This keeps large components maintainable and prevents hard-to-debug mutation and API design issues.
12 
13## Task List
14 
15- Compose complex behavior from small, focused composables
16- Use options objects for composables with multiple optional parameters
17- Return readonly state when updates must flow through explicit actions
18- Keep pure utility functions as plain utilities, not composables
19- Organize composable and component code by feature concern, and extract composables when components grow
20 
21## Compose Composables from Smaller Primitives
22 
23**BAD:**
24```vue
25<script setup>
26import { ref, computed, onMounted, onUnmounted } from 'vue'
27 
28const x = ref(0)
29const y = ref(0)
30const inside = ref(false)
31const el = ref(null)
32 
33function onMove(e) {
34  x.value = e.pageX
35  y.value = e.pageY
36  if (!el.value) return
37  const r = el.value.getBoundingClientRect()
38  inside.value = x.value >= r.left && x.value <= r.right &&
39    y.value >= r.top && y.value <= r.bottom
40}
41 
42onMounted(() => window.addEventListener('mousemove', onMove))
43onUnmounted(() => window.removeEventListener('mousemove', onMove))
44</script>
45```
46 
47**GOOD:**
48```javascript
49// composables/useEventListener.js
50import { onMounted, onUnmounted, toValue } from 'vue'
51 
52export function useEventListener(target, event, callback) {
53  onMounted(() => toValue(target).addEventListener(event, callback))
54  onUnmounted(() => toValue(target).removeEventListener(event, callback))
55}
56```
57 
58```javascript
59// composables/useMouse.js
60import { ref } from 'vue'
61import { useEventListener } from './useEventListener'
62 
63export function useMouse() {
64  const x = ref(0)
65  const y = ref(0)
66 
67  useEventListener(window, 'mousemove', (e) => {
68    x.value = e.pageX
69    y.value = e.pageY
70  })
71 
72  return { x, y }
73}
74```
75 
76```javascript
77// composables/useMouseInElement.js
78import { computed } from 'vue'
79import { useMouse } from './useMouse'
80 
81export function useMouseInElement(elementRef) {
82  const { x, y } = useMouse()
83 
84  const isOutside = computed(() => {
85    if (!elementRef.value) return true
86    const rect = elementRef.value.getBoundingClientRect()
87    return x.value < rect.left || x.value > rect.right ||
88      y.value < rect.top || y.value > rect.bottom
89  })
90 
91  return { x, y, isOutside }
92}
93```
94 
95## Use Options Object Pattern for Composable Parameters
96 
97**BAD:**
98```javascript
99export function useFetch(url, method, headers, timeout, retries, immediate) {
100  // hard to read and easy to misorder
101}
102 
103useFetch('/api/users', 'GET', null, 5000, 3, true)
104```
105 
106**GOOD:**
107```javascript
108export function useFetch(url, options = {}) {
109  const {
110    method = 'GET',
111    headers = {},
112    timeout = 30000,
113    retries = 0,
114    immediate = true
115  } = options
116 
117  // implementation
118  return { method, headers, timeout, retries, immediate }
119}
120 
121useFetch('/api/users', {
122  method: 'POST',
123  timeout: 5000,
124  retries: 3
125})
126```
127 
128```typescript
129interface UseCounterOptions {
130  initial?: number
131  min?: number
132  max?: number
133  step?: number
134}
135 
136export function useCounter(options: UseCounterOptions = {}) {
137  const { initial = 0, min = -Infinity, max = Infinity, step = 1 } = options
138  // implementation
139}
140```
141 
142## Return Readonly State with Explicit Actions
143 
144**BAD:**
145```javascript
146export function useCart() {
147  const items = ref([])
148  const total = computed(() => items.value.reduce((sum, item) => sum + item.price, 0))
149  return { items, total } // any consumer can mutate directly
150}
151 
152const { items } = useCart()
153items.value.push({ id: 1, price: 10 })
154```
155 
156**GOOD:**
157```javascript
158import { ref, computed, readonly } from 'vue'
159 
160export function useCart() {
161  const _items = ref([])
162 
163  const total = computed(() =>
164    _items.value.reduce((sum, item) => sum + item.price * item.quantity, 0)
165  )
166 
167  function addItem(product, quantity = 1) {
168    const existing = _items.value.find(item => item.id === product.id)
169    if (existing) {
170      existing.quantity += quantity
171      return
172    }
173    _items.value.push({ ...product, quantity })
174  }
175 
176  function removeItem(productId) {
177    _items.value = _items.value.filter(item => item.id !== productId)
178  }
179 
180  return {
181    items: readonly(_items),
182    total,
183    addItem,
184    removeItem
185  }
186}
187```
188 
189## Keep Utilities as Utilities
190 
191**BAD:**
192```javascript
193export function useFormatters() {
194  const formatDate = (date) => new Intl.DateTimeFormat('en-US').format(date)
195  const formatCurrency = (amount) =>
196    new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(amount)
197  return { formatDate, formatCurrency }
198}
199 
200const { formatDate } = useFormatters()
201```
202 
203**GOOD:**
204```javascript
205// utils/formatters.js
206export function formatDate(date) {
207  return new Intl.DateTimeFormat('en-US').format(date)
208}
209 
210export function formatCurrency(amount) {
211  return new Intl.NumberFormat('en-US', {
212    style: 'currency',
213    currency: 'USD'
214  }).format(amount)
215}
216```
217 
218```javascript
219// composables/useInvoiceSummary.js
220import { computed } from 'vue'
221import { formatCurrency } from '@/utils/formatters'
222 
223export function useInvoiceSummary(invoiceRef) {
224  const totalLabel = computed(() => formatCurrency(invoiceRef.value.total))
225  return { totalLabel }
226}
227```
228 
229## Organize Composable and Component Code by Feature Concern
230 
231**BAD:**
232```vue
233<script setup>
234import { ref, computed, watch, onMounted } from 'vue'
235 
236const searchQuery = ref('')
237const items = ref([])
238const selected = ref(null)
239const showModal = ref(false)
240const sortBy = ref('name')
241const filter = ref('all')
242const loading = ref(false)
243 
244const filtered = computed(() => items.value.filter(i => i.category === filter.value))
245function openModal() { showModal.value = true }
246const sorted = computed(() => [...filtered.value].sort(/* ... */))
247watch(searchQuery, () => { /* ... */ })
248onMounted(() => { /* ... */ })
249</script>
250```
251 
252**GOOD:**
253```vue
254<script setup>
255import { useItems } from '@/composables/useItems'
256import { useSearch } from '@/composables/useSearch'
257import { useSelectionModal } from '@/composables/useSelectionModal'
258 
259// Data
260const { items, loading, fetchItems } = useItems()
261 
262// Search/filter/sort
263const { query, visibleItems } = useSearch(items)
264 
265// Selection + modal
266const { selectedItem, isModalOpen, selectItem, closeModal } = useSelectionModal()
267</script>
268```
269 
270```javascript
271// composables/useItems.js
272import { ref, onMounted } from 'vue'
273 
274export function useItems() {
275  const items = ref([])
276  const loading = ref(false)
277 
278  async function fetchItems() {
279    loading.value = true
280    try {
281      items.value = await api.getItems()
282    } finally {
283      loading.value = false
284    }
285  }
286 
287  onMounted(fetchItems)
288  return { items, loading, fetchItems }
289}
290```
291