Kurs Vue.js · Moduł 9: Composables i VueUse

Composables w produkcji

7 min czytania ·
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 composables

Plik 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/inject dla 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, nextTick dla watcherów, testowanie asynchronicznych operacji
  • Optymalizacja - shallowRef dla 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?

  1. Projekt do wysłaniaLab Manager System - Mentor
  2. WideoPodsumowanie modułu

Przydatne artykuły