Kurs Vue.js · Moduł 9: Composables i VueUse
Composables w produkcji
W tej lekcji5
Ostatni etap przed wdrożeniem systemów NOVA LAB na Marsie - poznajmy sprawdzone wzorce stosowane w produkcyjnych aplikacjach Vue 3. Prototyp z trzema composables w jednym pliku działa świetnie, dopóki pracujesz sam. W produkcji composables jest kilkadziesiąt, pisze je kilka osób, a każdy błąd typu wychodzi dopiero u użytkownika. Potrzebujesz więc porządku w plikach, typów i elastycznej konfiguracji.
Organizacja plików composables
W dużych projektach kluczowa jest czytelna struktura plików. Najczęściej spotkasz folder composables, w którym każdy composable ma własny plik nazwany tak jak funkcja:
src/
composables/
useAuth.ts # Autoryzacja
useNotifications.ts # Powiadomienia
useSensors.ts # Dane sensorów
useTheme.ts # Motyw aplikacji
index.ts # Re-export wszystkich composablesPlik index.ts to tak zwany plik zbiorczy (barrel file): nie zawiera logiki, tylko ponownie eksportuje funkcje z pozostałych plików, żeby komponent mógł zaimportować wszystko z jednego miejsca:
// composables/index.ts - centralny punkt eksportu
export { useAuth } from './useAuth'
export { useNotifications } from './useNotifications'
export { useSensors } from './useSensors'
export { useTheme } from './useTheme'
// Import w komponencie - czysty i czytelny
import { useAuth, useNotifications } from '@/composables'Alias @ wskazuje folder src - projekty tworzone przez create-vue mają go skonfigurowanego w Vite i w TypeScript. Plik zbiorczy ma jednak swoją cenę: przewodnik wydajności Vite zaleca unikać takich plików, bo import jednej funkcji zmusza serwer deweloperski do pobrania i przetworzenia wszystkich re-eksportowanych modułów. W małym folderze to bez znaczenia, w dużym lepiej importować bezpośrednio, na przykład z '@/composables/useAuth'.
Typowanie composables z TypeScript
TypeScript zapewnia bezpieczeństwo typów i lepsze podpowiedzi IDE. Vue eksportuje typy Ref<T> dla refów i ComputedRef<T> dla wartości computed. Importujemy je ze słowem type, bo szablony create-vue włączają opcję verbatimModuleSyntax, która wymaga oznaczania importów samych typów. Parametr <T> czyni composable generycznym, więc zadziała z listą dowolnych elementów:
import { ref, computed, type Ref, type ComputedRef } from 'vue'
// Interfejs dla zwracanego API
interface UsePaginationReturn<T> {
currentPage: Ref<number>
totalPages: ComputedRef<number>
paginatedItems: ComputedRef<T[]>
goToPage: (page: number) => void
nextPage: () => void
prevPage: () => void
}
// Typowany composable
function usePagination<T>(
items: Ref<T[]>,
perPage: number = 10
): UsePaginationReturn<T> {
const currentPage = ref(1)
const totalPages = computed(() =>
Math.ceil(items.value.length / perPage)
)
const paginatedItems = computed(() => {
const start = (currentPage.value - 1) * perPage
return items.value.slice(start, start + perPage)
})
function goToPage(page: number) {
if (page >= 1 && page <= totalPages.value) {
currentPage.value = page
}
}
function nextPage() { goToPage(currentPage.value + 1) }
function prevPage() { goToPage(currentPage.value - 1) }
return {
currentPage,
totalPages,
paginatedItems,
goToPage,
nextPage,
prevPage
}
}Gdy przekażesz Ref<Experiment[]>, paginatedItems będzie miało typ ComputedRef<Experiment[]> i IDE podpowie pola eksperymentu. Jawny interfejs zwracanego API nie jest obowiązkowy, bo TypeScript sam wywnioskuje typ, ale dokumentuje publiczny kontrakt composable.
Composable z opcjami konfiguracyjnymi
Wzorzec opcji pozwala na elastyczną konfigurację composable - jak panele konfiguracyjne modułów NOVA LAB. Zamiast pięciu parametrów w ustalonej kolejności composable przyjmuje jeden obiekt, którego wszystkie pola są opcjonalne:
import { ref, onUnmounted } from 'vue'
interface UsePollingOptions {
interval?: number
immediate?: boolean
retryOnError?: boolean
maxRetries?: number
onError?: (error: Error) => void
}Znak zapytania oznacza pole opcjonalne, a onError to funkcja, którą użytkownik może podać, żeby dowiedzieć się o błędzie. Wartości domyślne ustawiamy w samym composable, przy destrukturyzacji opcji:
function usePolling<T>(
fetchFn: () => Promise<T>,
options: UsePollingOptions = {}
) {
const {
interval = 5000,
immediate = true,
retryOnError = true,
maxRetries = 3,
onError
} = options
const data = ref<T | null>(null)
const error = ref<Error | null>(null)
const isPolling = ref(false)
const retryCount = ref(0)
let timerId: ReturnType<typeof setInterval> | null = null
async function poll() {
try {
data.value = await fetchFn()
error.value = null
retryCount.value = 0
} catch (e) {
// catch dostaje unknown - zamieniamy go na Error
const err = e instanceof Error ? e : new Error(String(e))
error.value = err
onError?.(err)
if (!retryOnError || retryCount.value >= maxRetries) {
stopPolling()
return
}
retryCount.value++
}
}
function startPolling() {
if (isPolling.value) return
isPolling.value = true
if (immediate) poll()
timerId = setInterval(poll, interval)
}
function stopPolling() {
isPolling.value = false
if (timerId) {
clearInterval(timerId)
timerId = null
}
}
onUnmounted(stopPolling)
return { data, error, isPolling, retryCount, startPolling, stopPolling }
}Trzy szczegóły odróżniają ten kod od prototypu. W trybie strict zmienna z catch ma typ unknown, więc przed przekazaniem do onError zamieniamy ją na Error. Typ ReturnType<typeof setInterval> działa zarówno w przeglądarce, gdzie setInterval zwraca liczbę, jak i z typami Node.js, gdzie zwraca obiekt. A onError?.(err) wywołuje funkcję tylko wtedy, gdy ktoś ją podał. Po błędzie kolejne tyknięcie interwału jest ponowną próbą, aż do maxRetries. Tak wygląda użycie z własnymi opcjami:
// Użycie z opcjami
const sensorData = usePolling(
() => fetch('/api/sensors').then(r => r.json()),
{
interval: 3000,
immediate: true,
maxRetries: 5,
onError: (e) => console.error('Polling failed:', e)
}
)Pominięte retryOnError przyjmie wartość domyślną true. Kolejność pól nie ma znaczenia, a dodanie nowej opcji w przyszłości nie zepsuje istniejących wywołań.
Composable z provide/inject dla dużych aplikacji
W produkcyjnych aplikacjach często potrzebujemy współdzielonego stanu bez prop drilling, czyli bez przekazywania props przez kilka poziomów komponentów. Żeby inject znał typ dostarczanej wartości, Vue udostępnia InjectionKey<T> - symbol, który niesie informację o typie. Najpierw opisujemy dane i klucz:
import { ref, computed, provide, inject, readonly, type InjectionKey } from 'vue'
interface User {
id: string
name: string
}
interface AppNotification {
id: number
message: string
type: string
timestamp: Date
}
// Typ sklepu wyprowadzamy z funkcji, która go tworzy
type AppStore = ReturnType<typeof createAppStore>
const StoreKey: InjectionKey<AppStore> = Symbol('AppStore')Nazwa AppNotification zamiast Notification nie jest przypadkowa - Notification to wbudowany typ przeglądarki. ReturnType sprawia, że typ sklepu zawsze zgadza się z tym, co naprawdę zwraca funkcja poniżej:
// Tworzymy raz w komponencie głównym (App.vue)
function createAppStore() {
const user = ref<User | null>(null)
const isAuthenticated = computed(() => user.value !== null)
const notifications = ref<AppNotification[]>([])
function login(userData: User) { user.value = userData }
function logout() { user.value = null }
function notify(message: string, type = 'info') {
notifications.value.push({
id: Date.now(),
message,
type,
timestamp: new Date()
})
}
const store = {
user: readonly(user),
isAuthenticated,
notifications: readonly(notifications),
login,
logout,
notify
}
provide(StoreKey, store)
return store
}Komponenty dostają user i notifications tylko do odczytu, więc stan zmieniają wyłącznie metody sklepu. Pozostaje funkcja dla konsumentów:
// Używamy w dowolnym zagnieżdżonym komponencie
function useAppStore() {
const store = inject(StoreKey)
if (!store) {
throw new Error('useAppStore wymaga createAppStore w App.vue')
}
return store
}Dzięki InjectionKey wynik useAppStore() ma pełny typ i IDE podpowie login, notify czy user. Bez klucza z typem inject zwróciłby unknown.
Podsumowanie modułu
W tym module poznałeś zaawansowane techniki pracy z composables:
- Factory composables - tworzenie wielu instancji composable z różną konfiguracją
- Kompozycja - łączenie composables w większe systemy, composable używający innego composable
- Dependency Injection -
provide/injectdla współdzielonego stanu bez prop drilling - Reaktywne wzorce - Singleton, Event Bus, State Machine, Observer - wszystkie z reaktywnością Vue
- VueUse - 200+ gotowych composables (
useLocalStorage,useDark,useWindowSize) - Testowanie - unit testy composables z Vitest, mockowanie,
nextTickdla watcherów, testowanie asynchronicznych operacji - Optymalizacja -
shallowRefdla dużych danych, computed caching, unikanie wycieków pamięci i anulowanie żądań - Produkcja - TypeScript typowanie, organizacja plików, wzorzec opcji konfiguracyjnych
Te techniki pozwolą Ci budować skalowalne i wydajne aplikacje Vue 3 - gotowe na misje kosmiczne!
Moja rada: gdy composable ma więcej niż dwa parametry konfiguracyjne, przejdź na obiekt opcji z wartościami domyślnymi, a publiczne API opisz typami od pierwszej wersji. Typowanie w Vue pogłębisz w Laboratorium Kwantowym, a zarządzanie stanem globalnym przejmie Pinia, którą poznasz w Bazie Danych Misji. W edytorze poniżej sklep aplikacji działa przez provide/inject, a polling czujników korzysta z opcji konfiguracyjnych.
Zapamiętaj: composable gotowy do produkcji to moduł stacji z instrukcją obsługi - ma swoje miejsce w magazynie, opisane złącza i rozsądne ustawienia fabryczne.
Kod do tej lekcji: App.vue
<script setup>
import { ref, computed, provide, inject, readonly, onUnmounted } from 'vue'
// ===== DEMO: COMPOSABLES W PRODUKCJI =====
// 1. Typowany composable w stylu TypeScript, z opcjami
const StoreKey = Symbol('AppStore')
function createAppStore() {
const user = ref({ name: 'Dr. Nova', role: 'komandor' })
const isAuthenticated = computed(() => user.value !== null)
const notifications = ref([])
function notify(message, type = 'info') {
notifications.value.unshift({ id: Date.now(), message, type, timestamp: new Date().toLocaleTimeString() })
if (notifications.value.length > 10) notifications.value.pop()
}
function logout() { user.value = null }
const store = { user: readonly(user), isAuthenticated, notifications: readonly(notifications), notify, logout }
provide(StoreKey, store)
return store
}
function useAppStore() {
const store = inject(StoreKey)
if (!store) throw new Error('Brak store - nie wywołano provide')
return store
}
// 2. Composable do pollingu ze wzorcem opcji
function usePolling(fetchFn, options = {}) {
const { interval = 3000, immediate = true, maxRetries = 3, onError } = options
const data = ref(null)
const error = ref(null)
const isPolling = ref(false)
const retryCount = ref(0)
const pollCount = ref(0)
let timerId = null
async function poll() {
try {
data.value = await fetchFn()
error.value = null
retryCount.value = 0
pollCount.value++
} catch (e) {
error.value = e.message || 'Błąd'
onError?.(e)
if (retryCount.value >= maxRetries) { stopPolling(); return }
retryCount.value++
}
}
function startPolling() {
if (isPolling.value) return
isPolling.value = true
if (immediate) poll()
timerId = setInterval(poll, interval)
}
function stopPolling() {
isPolling.value = false
if (timerId) { clearInterval(timerId); timerId = null }
}
onUnmounted(stopPolling)
return { data, error, isPolling, retryCount, pollCount, startPolling, stopPolling }
}
// === Konfiguracja ===
const store = createAppStore()
// Symulacja API czujników
const sensorPolling = usePolling(
async () => {
await new Promise(r => setTimeout(r, 500))
if (Math.random() < 0.15) throw new Error('Przekroczony czas odpowiedzi czujnika')
return {
temperature: Math.round(-60 + Math.random() * 80),
pressure: Math.round(90 + Math.random() * 30),
oxygen: Math.round(85 + Math.random() * 15),
timestamp: new Date().toLocaleTimeString()
}
},
{
interval: 2000,
immediate: true,
maxRetries: 5,
onError: (e) => store.notify('Błąd czujnika: ' + e.message, 'danger')
}
)
</script>
<template>
<div class="prod-lab">
<h1>Composables w Produkcji - NOVA LAB</h1>
<section>
<h2>Store aplikacji (provide/inject)</h2>
<div v-if="store.isAuthenticated.value" class="user-info">
<p>Użytkownik: {{ store.user.value.name }} ({{ store.user.value.role }})</p>
<button @click="store.logout()">Wyloguj</button>
</div>
<p v-else class="warn">Brak zalogowanego użytkownika</p>
<button @click="store.notify('Kontrola systemu OK', 'info')">Dodaj informację</button>
<button @click="store.notify('Niski poziom baterii', 'warning')">Dodaj ostrzeżenie</button>
<div class="notifs">
<div v-for="n in store.notifications.value" :key="n.id" class="notif" :class="n.type">
<span class="time">{{ n.timestamp }}</span> {{ n.message }}
</div>
</div>
</section>
<section>
<h2>Polling z opcjami</h2>
<div class="poll-controls">
<button @click="sensorPolling.startPolling()" :disabled="sensorPolling.isPolling.value" class="start">Start</button>
<button @click="sensorPolling.stopPolling()" :disabled="!sensorPolling.isPolling.value" class="stop">Stop</button>
</div>
<p class="poll-info">
Polling: {{ sensorPolling.isPolling.value ? 'AKTYWNY' : 'ZATRZYMANY' }} |
Odpytania: {{ sensorPolling.pollCount.value }} |
Ponowienia: {{ sensorPolling.retryCount.value }}
</p>
<div v-if="sensorPolling.data.value" class="sensor-data">
<div class="sensor">Temp.: {{ sensorPolling.data.value.temperature }}°C</div>
<div class="sensor">Ciśnienie: {{ sensorPolling.data.value.pressure }} kPa</div>
<div class="sensor">O2: {{ sensorPolling.data.value.oxygen }}%</div>
<div class="sensor time">{{ sensorPolling.data.value.timestamp }}</div>
</div>
<div v-if="sensorPolling.error.value" class="error">{{ sensorPolling.error.value }}</div>
</section>
</div>
</template>
<style scoped>
.prod-lab { background: #0a0e27; color: #e0e0ff; padding: 1.5rem; min-height: 100vh; font-family: 'Courier New', monospace; }
h1 { color: #00ff88; text-align: center; }
h2 { color: #00b4d8; border-bottom: 1px solid #00b4d8; padding-bottom: 0.5rem; }
section { margin: 1.5rem 0; }
button { background: #00b4d8; color: #fff; border: none; padding: 0.4rem 0.8rem; border-radius: 4px; cursor: pointer; margin: 0.2rem; font-family: inherit; }
button:hover { background: #00ff88; color: #0a0e27; }
button:disabled { opacity: 0.4; }
button.start { background: #00ff88; color: #0a0e27; }
button.stop { background: #ff0055; }
.user-info { background: rgba(0,255,136,0.1); border: 1px solid #00ff88; border-radius: 6px; padding: 0.8rem; margin: 0.5rem 0; }
.warn { color: #ffb400; }
.notifs { margin-top: 0.5rem; max-height: 200px; overflow-y: auto; }
.notif { font-size: 0.8rem; padding: 0.3rem 0.6rem; margin: 0.2rem 0; border-radius: 3px; }
.notif.info { background: rgba(0,180,216,0.1); border-left: 3px solid #00b4d8; }
.notif.warning { background: rgba(255,180,0,0.1); border-left: 3px solid #ffb400; }
.notif.danger { background: rgba(255,0,85,0.1); border-left: 3px solid #ff0055; }
.time { color: #888; margin-right: 0.5rem; font-size: 0.75rem; }
.poll-controls { display: flex; gap: 0.5rem; margin: 0.5rem 0; }
.poll-info { color: #00b4d8; font-size: 0.9rem; }
.sensor-data { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: 0.5rem; margin: 0.5rem 0; }
.sensor { background: rgba(0,180,216,0.1); border: 1px solid #00b4d8; border-radius: 6px; padding: 0.6rem; text-align: center; font-weight: bold; }
.sensor.time { color: #888; font-weight: normal; font-size: 0.8rem; }
.error { background: rgba(255,0,85,0.1); border: 1px solid #ff0055; color: #ff0055; padding: 0.5rem; border-radius: 4px; margin: 0.5rem 0; }
</style>Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?