792 lines
20 KiB
Markdown
792 lines
20 KiB
Markdown
# Vue Composables Best Practices Reference
|
|
|
|
## Table of Contents
|
|
- [What is a Composable?](#what-is-a-composable)
|
|
- [Inline vs External Composables](#inline-vs-external-composables)
|
|
- [File Naming and Structure](#file-naming-and-structure)
|
|
- [Composable Anatomy](#composable-anatomy)
|
|
- [Single Responsibility Principle](#single-responsibility-principle)
|
|
- [Argument Passing](#argument-passing)
|
|
- [Error Handling](#error-handling)
|
|
- [Separation of Concerns: No UI Logic](#separation-of-concerns-no-ui-logic-in-composables)
|
|
- [Functional Core, Imperative Shell](#functional-core-imperative-shell-optional-pattern)
|
|
- [Consistent File Structure](#consistent-file-structure)
|
|
- [Composable Composition](#composable-composition)
|
|
- [Return Values](#return-values)
|
|
- [TypeScript Best Practices](#typescript-best-practices)
|
|
- [Common Patterns](#common-patterns)
|
|
- [Testing Composables](#testing-composables)
|
|
- [Common Mistakes](#common-mistakes)
|
|
- [Quick Checklist](#quick-checklist)
|
|
|
|
## What is a Composable?
|
|
|
|
Composables encapsulate reusable stateful logic using Vue's Composition API.
|
|
|
|
## Inline vs External Composables
|
|
|
|
**CRITICAL PRINCIPLE:** Start with inline composables for component-specific logic. Only extract to external files when the logic is reused in multiple components.
|
|
|
|
### The Decision Framework
|
|
|
|
```ts
|
|
// ✅ CORRECT: Component-specific logic stays INLINE
|
|
<script setup lang="ts">
|
|
// Inline composable - used only in this component
|
|
function useHiddenFolders() {
|
|
const showHidden = ref(localStorage.getItem('show-hidden') === 'true')
|
|
|
|
watch(showHidden, (value) => {
|
|
if (value) {
|
|
localStorage.setItem('show-hidden', 'true')
|
|
} else {
|
|
localStorage.removeItem('show-hidden')
|
|
}
|
|
})
|
|
|
|
return { showHidden }
|
|
}
|
|
|
|
// Use the inline composable
|
|
const { showHidden } = useHiddenFolders()
|
|
</script>
|
|
|
|
// ❌ WRONG: Extracting to external file when used in ONE component
|
|
// src/composables/useHiddenFolders.ts - only used in one place!
|
|
export function useHiddenFolders() { /* ... */ }
|
|
```
|
|
|
|
### When to Use Each Approach
|
|
|
|
| Pattern | When to Use | Example |
|
|
|---------|-------------|---------|
|
|
| **Inline composable** | Logic specific to ONE component | Form validation, local UI state, component-specific data fetching |
|
|
| **External composable** | Logic reused in 2+ components | Authentication, global state, shared API calls |
|
|
|
|
### Real-World Example: FolderManager Component
|
|
|
|
This example shows inline composables organizing component logic:
|
|
|
|
```vue
|
|
<script setup lang="ts">
|
|
import { ref, watch } from 'vue'
|
|
import { useQuery, mutate } from 'vue-apollo'
|
|
|
|
// External composables (reusable across app)
|
|
import { useNetworkState } from '@/composables/useNetworkState'
|
|
|
|
// GraphQL queries
|
|
import FOLDERS_FAVORITE from '@/graphql/folder/favoriteFolders.gql'
|
|
import FOLDER_SET_FAVORITE from '@/graphql/folder/folderSetFavorite.gql'
|
|
|
|
// Network state (reusable)
|
|
const { networkState } = useNetworkState()
|
|
|
|
// Component-specific logic as inline composables
|
|
const { showHiddenFolders } = useHiddenFolders()
|
|
const { favoriteFolders, toggleFavorite } = useFavoriteFolders()
|
|
|
|
// Inline composable #1: Hidden folders management
|
|
function useHiddenFolders() {
|
|
const showHiddenFolders = ref(
|
|
localStorage.getItem('show-hidden-folders') === 'true'
|
|
)
|
|
|
|
watch(showHiddenFolders, (value) => {
|
|
if (value) {
|
|
localStorage.setItem('show-hidden-folders', 'true')
|
|
} else {
|
|
localStorage.removeItem('show-hidden-folders')
|
|
}
|
|
})
|
|
|
|
return { showHiddenFolders }
|
|
}
|
|
|
|
// Inline composable #2: Favorite folders management
|
|
function useFavoriteFolders() {
|
|
const favoriteFolders = useQuery(FOLDERS_FAVORITE, [])
|
|
|
|
async function toggleFavorite(folderPath: string) {
|
|
await mutate({
|
|
mutation: FOLDER_SET_FAVORITE,
|
|
variables: { path: folderPath }
|
|
})
|
|
}
|
|
|
|
return { favoriteFolders, toggleFavorite }
|
|
}
|
|
</script>
|
|
|
|
<template>
|
|
<div>
|
|
<input v-model="showHiddenFolders" type="checkbox" />
|
|
<ul>
|
|
<li v-for="folder in favoriteFolders" :key="folder.path">
|
|
{{ folder.name }}
|
|
<button @click="toggleFavorite(folder.path)">Toggle</button>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</template>
|
|
```
|
|
|
|
### Benefits of Inline Composables
|
|
|
|
**Readability:**
|
|
- Related logic grouped together
|
|
- Clear component structure at a glance
|
|
- No need to jump between files
|
|
|
|
**Maintainability:**
|
|
- Changes stay in one file
|
|
- No premature abstraction
|
|
- Easier to understand component behavior
|
|
|
|
**Flexibility:**
|
|
- Easy to refactor when needed
|
|
- Can access component-specific imports
|
|
- Simple to extract later if reused
|
|
|
|
### When to Extract to External File
|
|
|
|
Extract an inline composable to `src/composables/` when:
|
|
|
|
1. **Used in 2+ components** - Actual reuse, not "might be reused"
|
|
2. **Shared business logic** - Authentication, API patterns, etc.
|
|
3. **Testing isolation needed** - Complex logic requiring dedicated tests
|
|
|
|
```ts
|
|
// After you use the SAME logic in a second component, extract it:
|
|
|
|
// src/composables/useHiddenFolders.ts
|
|
export function useHiddenFolders() {
|
|
const showHiddenFolders = ref(
|
|
localStorage.getItem('show-hidden-folders') === 'true'
|
|
)
|
|
|
|
watch(showHiddenFolders, (value) => {
|
|
if (value) {
|
|
localStorage.setItem('show-hidden-folders', 'true')
|
|
} else {
|
|
localStorage.removeItem('show-hidden-folders')
|
|
}
|
|
})
|
|
|
|
return { showHiddenFolders }
|
|
}
|
|
```
|
|
|
|
### Common Anti-Patterns
|
|
|
|
```ts
|
|
// ❌ WRONG: Extracting too early
|
|
// Creating external composable used in only ONE component
|
|
// src/composables/useComponentSpecificThing.ts - only used once!
|
|
|
|
// ❌ WRONG: Not organizing component logic
|
|
// Flat <script setup> with mixed concerns
|
|
<script setup lang="ts">
|
|
const showHidden = ref(localStorage.getItem('show-hidden') === 'true')
|
|
watch(showHidden, (value) => { /* ... */ })
|
|
|
|
const favoriteFolders = useQuery(FOLDERS_FAVORITE, [])
|
|
async function toggleFavorite() { /* ... */ }
|
|
|
|
// ...hundreds of lines of mixed logic
|
|
</script>
|
|
|
|
// ✅ CORRECT: Inline composables organize component
|
|
<script setup lang="ts">
|
|
const { showHidden } = useHiddenFolders()
|
|
const { favoriteFolders, toggleFavorite } = useFavoriteFolders()
|
|
|
|
function useHiddenFolders() { /* grouped logic */ }
|
|
function useFavoriteFolders() { /* grouped logic */ }
|
|
</script>
|
|
```
|
|
|
|
### Quick Decision Checklist
|
|
|
|
- [ ] Is this logic used in only ONE component? → Inline composable
|
|
- [ ] Does it organize complex component logic? → Inline composable
|
|
- [ ] Is it actually reused in 2+ components NOW? → External composable
|
|
- [ ] Is it shared business logic (auth, API)? → External composable
|
|
- [ ] Might it be reused someday? → Keep inline until that day comes
|
|
|
|
**Remember:** Premature extraction is premature optimization. Start inline, extract when you have proof of reuse.
|
|
|
|
## File Naming and Structure
|
|
|
|
**Note:** This section applies to **external composables** in `src/composables/`. Inline composables (defined within components) don't need separate files.
|
|
|
|
### Naming Convention
|
|
|
|
```
|
|
✅ CORRECT:
|
|
src/composables/
|
|
useCounter.ts // External - reused in multiple components
|
|
useUserData.ts // External - shared business logic
|
|
useApiRequest.ts // External - used across app
|
|
|
|
❌ WRONG:
|
|
src/composables/
|
|
counter.ts // Missing 'use' prefix
|
|
APIrequest.ts // Wrong casing
|
|
user-data.ts // Wrong casing
|
|
useComponentSpecificThing.ts // Should be inline in component!
|
|
```
|
|
|
|
**Rules for External Composables:**
|
|
- ALWAYS prefix with `use`
|
|
- ALWAYS use PascalCase after `use`: `useUserData` not `useuserdata`
|
|
- Place in `src/composables/` directory
|
|
- One composable per file
|
|
- Only extract when reused in 2+ components
|
|
|
|
### Function Naming
|
|
|
|
```ts
|
|
// ✅ CORRECT: Descriptive names
|
|
export function useUserData() {}
|
|
export function useApiRequest() {}
|
|
export function useLocalStorage() {}
|
|
|
|
// ❌ WRONG: Too generic
|
|
export function useData() {}
|
|
export function useRequest() {}
|
|
export function useStorage() {}
|
|
```
|
|
|
|
## Composable Anatomy
|
|
|
|
A well-structured composable has three parts:
|
|
|
|
```ts
|
|
export function useUserData(userId: string) {
|
|
// 1. PRIMARY STATE - Main reactive data
|
|
const user = ref<User | null>(null)
|
|
|
|
// 2. STATE METADATA - Supporting state (loading, error, etc.)
|
|
const status = ref<'idle' | 'loading' | 'success' | 'error'>('idle')
|
|
const error = ref<Error | null>(null)
|
|
|
|
// 3. METHODS - Functions that update state
|
|
const fetchUser = async () => {
|
|
status.value = 'loading'
|
|
error.value = null
|
|
|
|
try {
|
|
const response = await axios.get(`/api/users/${userId}`)
|
|
user.value = response.data
|
|
status.value = 'success'
|
|
} catch (e) {
|
|
error.value = e as Error
|
|
status.value = 'error'
|
|
}
|
|
}
|
|
|
|
return { user, status, error, fetchUser }
|
|
}
|
|
```
|
|
|
|
**Structure Order:**
|
|
1. Primary State (the main data)
|
|
2. State Metadata (loading, error, etc.)
|
|
3. Methods (functions that manipulate state)
|
|
|
|
## Single Responsibility Principle
|
|
|
|
Each composable should do ONE thing well.
|
|
|
|
```ts
|
|
// ✅ CORRECT: Single responsibility
|
|
export function useCounter() {
|
|
const count = ref(0)
|
|
|
|
const increment = () => count.value++
|
|
const decrement = () => count.value--
|
|
const reset = () => count.value = 0
|
|
|
|
return { count, increment, decrement, reset }
|
|
}
|
|
|
|
// ❌ WRONG: Multiple responsibilities
|
|
export function useUserAndCounter(userId: string) {
|
|
// User management
|
|
const user = ref<User | null>(null)
|
|
const fetchUser = async () => { /* ... */ }
|
|
|
|
// Counter logic (unrelated!)
|
|
const count = ref(0)
|
|
const increment = () => count.value++
|
|
|
|
return { user, fetchUser, count, increment }
|
|
}
|
|
```
|
|
|
|
**Fix:** Create two composables: `useUser` and `useCounter`.
|
|
|
|
## Argument Passing
|
|
|
|
### Four or More Parameters: Use Object
|
|
|
|
```ts
|
|
// ✅ CORRECT: Object for 4+ parameters
|
|
useUserData({
|
|
id: 1,
|
|
fetchOnMount: true,
|
|
token: 'abc',
|
|
locale: 'en'
|
|
})
|
|
|
|
// ✅ CORRECT: Individual args for 3 or fewer
|
|
useCounter(initialValue, autoIncrement, storageKey)
|
|
|
|
// ❌ WRONG: Many individual args
|
|
useUserData(1, true, 'abc', 'en', false, null)
|
|
```
|
|
|
|
**With TypeScript:**
|
|
|
|
```ts
|
|
interface UseUserDataOptions {
|
|
id: number
|
|
fetchOnMount?: boolean
|
|
token?: string
|
|
locale?: string
|
|
}
|
|
|
|
export function useUserData(options: UseUserDataOptions) {
|
|
const { id, fetchOnMount = false, token, locale = 'en' } = options
|
|
// ...
|
|
}
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
ALWAYS expose error state, NEVER just console.error.
|
|
|
|
```ts
|
|
// ✅ CORRECT: Expose errors
|
|
export function useUserData(userId: string) {
|
|
const user = ref<User | null>(null)
|
|
const error = ref<Error | null>(null)
|
|
|
|
const fetchUser = async () => {
|
|
try {
|
|
const response = await axios.get(`/api/users/${userId}`)
|
|
user.value = response.data
|
|
} catch (e) {
|
|
error.value = e as Error // Expose to caller
|
|
}
|
|
}
|
|
|
|
return { user, error, fetchUser }
|
|
}
|
|
|
|
// ❌ WRONG: Swallow errors
|
|
export function useUserDataBad(userId: string) {
|
|
const user = ref<User | null>(null)
|
|
|
|
const fetchUser = async () => {
|
|
try {
|
|
const response = await axios.get(`/api/users/${userId}`)
|
|
user.value = response.data
|
|
} catch (e) {
|
|
console.error('Error:', e) // Component can't handle error
|
|
}
|
|
}
|
|
|
|
return { user, fetchUser } // No error exposed
|
|
}
|
|
```
|
|
|
|
## Separation of Concerns: No UI Logic in Composables
|
|
|
|
Composables handle STATE and BUSINESS LOGIC only. UI concerns (toasts, alerts, modals) belong in components.
|
|
|
|
```ts
|
|
// ✅ CORRECT: Business logic only
|
|
export function useUserData(userId: string) {
|
|
const user = ref<User | null>(null)
|
|
const error = ref<Error | null>(null)
|
|
const status = ref<'idle' | 'loading' | 'success' | 'error'>('idle')
|
|
|
|
const fetchUser = async () => {
|
|
status.value = 'loading'
|
|
try {
|
|
const response = await axios.get(`/api/users/${userId}`)
|
|
user.value = response.data
|
|
status.value = 'success'
|
|
} catch (e) {
|
|
error.value = e as Error
|
|
status.value = 'error'
|
|
}
|
|
}
|
|
|
|
return { user, error, status, fetchUser }
|
|
}
|
|
|
|
// In component - UI layer handles presentation
|
|
const { user, error, status, fetchUser } = useUserData(userId)
|
|
|
|
watch(status, (s) => {
|
|
if (s === 'success') showToast('Success!') // UI in component
|
|
if (s === 'error') showToast(`Error: ${error.value?.message}`)
|
|
})
|
|
|
|
// ❌ WRONG: UI logic in composable
|
|
export function useUserDataBad(userId: string) {
|
|
const user = ref<User | null>(null)
|
|
|
|
const fetchUser = async () => {
|
|
try {
|
|
const response = await axios.get(`/api/users/${userId}`)
|
|
user.value = response.data
|
|
} catch (e) {
|
|
showToast('Failed to load user') // UI logic in composable
|
|
}
|
|
}
|
|
|
|
return { user, fetchUser }
|
|
}
|
|
```
|
|
|
|
**Why separation matters:**
|
|
- Composable is testable without mocking UI
|
|
- Different components can use different UI (toast, modal, inline error)
|
|
- Composable works in non-UI contexts (background tasks, SSR)
|
|
- Follows separation of concerns
|
|
|
|
## Functional Core, Imperative Shell (Optional Pattern)
|
|
|
|
Separate pure functions (core logic) from side effects (shell).
|
|
|
|
```ts
|
|
// ✅ CORRECT: Functional core, imperative shell
|
|
// Functional Core (pure, testable)
|
|
const calculate = (a: number, b: number) => a + b
|
|
const multiply = (a: number, b: number) => a * b
|
|
|
|
// Imperative Shell (Vue reactivity, side effects)
|
|
export function useCalculator() {
|
|
const result = ref(0)
|
|
|
|
const add = (a: number, b: number) => {
|
|
result.value = calculate(a, b) // Use pure function
|
|
}
|
|
|
|
const times = (a: number, b: number) => {
|
|
result.value = multiply(a, b)
|
|
}
|
|
|
|
return { result, add, times }
|
|
}
|
|
|
|
// ❌ WRONG: Mixed concerns
|
|
export function useCalculatorBad() {
|
|
const result = ref(0)
|
|
|
|
const add = (a: number, b: number) => {
|
|
console.log('Adding:', a, b) // Side effect mixed with logic
|
|
result.value = a + b
|
|
}
|
|
|
|
return { result, add }
|
|
}
|
|
```
|
|
|
|
**Benefits:**
|
|
- Pure functions are easy to test
|
|
- Side effects isolated to shell
|
|
- Better separation of concerns
|
|
|
|
## Consistent File Structure
|
|
|
|
Maintain consistent ordering within composable files:
|
|
|
|
```ts
|
|
import { ref, computed, watch, onMounted } from 'vue'
|
|
|
|
export function useExample() {
|
|
// 1. INITIALIZING
|
|
// Setup, imports, router, other composables
|
|
const router = useRouter()
|
|
const { user } = useAuth()
|
|
|
|
// 2. REFS
|
|
const count = ref(0)
|
|
const data = ref<Data | null>(null)
|
|
|
|
// 3. COMPUTED
|
|
const isEven = computed(() => count.value % 2 === 0)
|
|
const hasData = computed(() => data.value !== null)
|
|
|
|
// 4. METHODS
|
|
const increment = () => count.value++
|
|
const fetchData = async () => { /* ... */ }
|
|
|
|
// 5. LIFECYCLE HOOKS
|
|
onMounted(() => {
|
|
fetchData()
|
|
})
|
|
|
|
// 6. WATCH
|
|
watch(count, (newCount) => {
|
|
console.log('Count changed:', newCount)
|
|
})
|
|
|
|
return { count, isEven, increment, data, fetchData }
|
|
}
|
|
```
|
|
|
|
**Recommended Order:**
|
|
1. Initializing (setup, other composables)
|
|
2. Refs (reactive state)
|
|
3. Computed (derived state)
|
|
4. Methods (functions)
|
|
5. Lifecycle Hooks (onMounted, onUnmounted, etc.)
|
|
6. Watch (watchers)
|
|
|
|
## Composable Composition
|
|
|
|
Composables can use other composables:
|
|
|
|
```ts
|
|
// ✅ CORRECT: Composing composables
|
|
export function useAuthenticatedUser(userId: string) {
|
|
const { token, isAuthenticated } = useAuth()
|
|
const { user, error, fetchUser } = useUserData(userId)
|
|
|
|
// Only fetch if authenticated
|
|
watchEffect(() => {
|
|
if (isAuthenticated.value && token.value) {
|
|
fetchUser()
|
|
}
|
|
})
|
|
|
|
return { user, error, isAuthenticated }
|
|
}
|
|
```
|
|
|
|
**Rules for composition:**
|
|
- Call composables at the top of your composable function
|
|
- Don't call composables conditionally
|
|
- Compose related functionality (auth + user data)
|
|
- Maintain single responsibility even when composing
|
|
|
|
## Return Values
|
|
|
|
Return an object with named properties for clarity:
|
|
|
|
```ts
|
|
// ✅ CORRECT: Named object return
|
|
export function useCounter() {
|
|
const count = ref(0)
|
|
const increment = () => count.value++
|
|
|
|
return { count, increment }
|
|
}
|
|
|
|
// Usage
|
|
const { count, increment } = useCounter()
|
|
|
|
// ❌ WRONG: Array return (unclear)
|
|
export function useCounterBad() {
|
|
const count = ref(0)
|
|
const increment = () => count.value++
|
|
|
|
return [count, increment] // Which is which?
|
|
}
|
|
```
|
|
|
|
## TypeScript Best Practices
|
|
|
|
```ts
|
|
// ✅ CORRECT: Proper typing
|
|
interface User {
|
|
id: number
|
|
name: string
|
|
email: string
|
|
}
|
|
|
|
interface UseUserDataReturn {
|
|
user: Ref<User | null>
|
|
error: Ref<Error | null>
|
|
status: Ref<'idle' | 'loading' | 'success' | 'error'>
|
|
fetchUser: () => Promise<void>
|
|
}
|
|
|
|
export function useUserData(userId: string): UseUserDataReturn {
|
|
const user = ref<User | null>(null)
|
|
const error = ref<Error | null>(null)
|
|
const status = ref<'idle' | 'loading' | 'success' | 'error'>('idle')
|
|
|
|
const fetchUser = async () => {
|
|
status.value = 'loading'
|
|
try {
|
|
const response = await axios.get<User>(`/api/users/${userId}`)
|
|
user.value = response.data
|
|
status.value = 'success'
|
|
} catch (e) {
|
|
error.value = e as Error
|
|
status.value = 'error'
|
|
}
|
|
}
|
|
|
|
return { user, error, status, fetchUser }
|
|
}
|
|
```
|
|
|
|
## Common Patterns
|
|
|
|
### Loading State Pattern
|
|
|
|
```ts
|
|
export function useAsyncData<T>(fetcher: () => Promise<T>) {
|
|
const data = ref<T | null>(null)
|
|
const error = ref<Error | null>(null)
|
|
const isLoading = ref(false)
|
|
|
|
const execute = async () => {
|
|
isLoading.value = true
|
|
error.value = null
|
|
|
|
try {
|
|
data.value = await fetcher()
|
|
} catch (e) {
|
|
error.value = e as Error
|
|
} finally {
|
|
isLoading.value = false
|
|
}
|
|
}
|
|
|
|
return { data, error, isLoading, execute }
|
|
}
|
|
```
|
|
|
|
### LocalStorage Sync Pattern
|
|
|
|
```ts
|
|
export function useLocalStorage<T>(key: string, defaultValue: T) {
|
|
const data = ref<T>(defaultValue)
|
|
|
|
// Load from localStorage on init
|
|
const stored = localStorage.getItem(key)
|
|
if (stored) {
|
|
try {
|
|
data.value = JSON.parse(stored)
|
|
} catch (e) {
|
|
console.warn('Failed to parse stored value')
|
|
}
|
|
}
|
|
|
|
// Sync to localStorage on change
|
|
watch(data, (newValue) => {
|
|
localStorage.setItem(key, JSON.stringify(newValue))
|
|
}, { deep: true })
|
|
|
|
return data
|
|
}
|
|
```
|
|
|
|
### Debounced Input Pattern
|
|
|
|
```ts
|
|
export function useDebouncedRef<T>(value: T, delay = 300) {
|
|
const immediate = ref(value)
|
|
const debounced = ref(value)
|
|
|
|
watch(immediate, (newValue) => {
|
|
setTimeout(() => {
|
|
debounced.value = newValue
|
|
}, delay)
|
|
})
|
|
|
|
return { immediate, debounced }
|
|
}
|
|
```
|
|
|
|
## Testing Composables
|
|
|
|
```ts
|
|
import { describe, it, expect } from 'vitest'
|
|
import { useCounter } from './useCounter'
|
|
|
|
describe('useCounter', () => {
|
|
it('increments count', () => {
|
|
const { count, increment } = useCounter()
|
|
|
|
expect(count.value).toBe(0)
|
|
increment()
|
|
expect(count.value).toBe(1)
|
|
})
|
|
|
|
it('decrements count', () => {
|
|
const { count, decrement } = useCounter()
|
|
|
|
count.value = 5
|
|
decrement()
|
|
expect(count.value).toBe(4)
|
|
})
|
|
})
|
|
```
|
|
|
|
For async composables, use Vue Test Utils:
|
|
|
|
```ts
|
|
import { mount } from '@vue/test-utils'
|
|
|
|
it('fetches user data', async () => {
|
|
const wrapper = mount({
|
|
setup() {
|
|
return useUserData('123')
|
|
},
|
|
template: '<div></div>'
|
|
})
|
|
|
|
const { fetchUser, user, status } = wrapper.vm
|
|
|
|
await fetchUser()
|
|
|
|
expect(status.value).toBe('success')
|
|
expect(user.value).toBeDefined()
|
|
})
|
|
```
|
|
|
|
## Common Mistakes
|
|
|
|
| Mistake | Fix |
|
|
|---------|-----|
|
|
| Extracting to external file too early | Start inline, extract when reused in 2+ components |
|
|
| External composable used in only ONE component | Move to inline composable in that component |
|
|
| Missing `use` prefix | Always prefix: `useCounter` not `counter` |
|
|
| UI logic in composable | Move toasts/alerts to component |
|
|
| Multiple responsibilities | Split into focused composables |
|
|
| Not exposing errors | Always return error state |
|
|
| Too many parameters | Use object for 4+ params |
|
|
| Conditional composable calls | Call composables at top level only |
|
|
| Array returns | Use named object returns |
|
|
| Missing TypeScript types | Type all refs and return values |
|
|
|
|
## Quick Checklist
|
|
|
|
**Before Creating External Composable:**
|
|
- [ ] Is this logic used in 2+ components? (If not, keep inline)
|
|
- [ ] Is this shared business logic that should be centralized?
|
|
|
|
**For All Composables (Inline and External):**
|
|
- [ ] Single responsibility (one thing well)
|
|
- [ ] Exposes error state (not just console.error)
|
|
- [ ] No UI logic (toasts, alerts, modals)
|
|
- [ ] Consistent internal structure (refs → computed → methods → lifecycle → watch)
|
|
- [ ] Named object return (not array)
|
|
- [ ] Full TypeScript types
|
|
- [ ] 4+ params use object, 3 or fewer use individual args
|
|
|
|
**For External Composables Only:**
|
|
- [ ] File named with `use` prefix and PascalCase
|
|
- [ ] Located in `src/composables/` directory
|
|
- [ ] Actually reused in multiple components (not "might be reused")
|