vue-patterns

name	vue-patterns
description	Use whenever writing or reviewing Vue code in this repo's admin SPA (frontend/src/admin). Covers Vue 3 Composition API, `<script setup lang="ts">`, Pinia stores, Vue Router, composables, Vite, and common anti-patterns.

Vue Patterns Skill (live.moafunk.de admin SPA)

The admin dashboard lives in frontend/src/admin/ — Vue 3 + Vite + Pinia + Vue Router, TypeScript strict. The public pages are vanilla TS (no framework). Apply this skill to the admin SPA.

Defaults

• <script setup lang="ts"> for every component. Composition API only — no Options API in new code.
• TypeScript strict. Type props with defineProps<{ ... }>() (type-based), emits with defineEmits<{ ... }>(). Never any.
• ref for primitives, reactive only for grouped object state; prefer ref + .value for predictability.
• computed for derived state — never duplicate state you can derive.
• One component = one responsibility. Extract reusable logic into composables (useXxx) under frontend/src/admin/composables/.
• Co-locate component-scoped styles with <style scoped>.

Reactivity rules (the real ones)

• Don't destructure props (loses reactivity) — use toRefs(props) or reference props.x directly. For store state use storeToRefs(store).
• watch explicit sources; watchEffect only when the dependency set is obvious. Clean up listeners/timers in onUnmounted (or the watch/watchEffect cleanup callback) — critical for the WebSocket/stream and wavesurfer/flv.js views.
• Keep refs stable; never reassign a reactive object wholesale (mutate fields or use a ref).

State — when to reach for what

Need	Use
Local component state	ref / computed
Reusable stateful logic	a composable (useStream, useUpload, …)
Cross-view shared/app state	a Pinia store (frontend/src/admin/stores/)
Server data	the API client in frontend/src/admin/api/ (see ApiClient); keep fetch logic in composables/stores, not components
Auth/route guards	Vue Router guards + the auth store (router.ts)

Pinia

• defineStore('name', () => { ... }) (setup-store style) to match Composition API. Return ref/computed/actions.
• Read reactive state in components via storeToRefs(store); call actions directly.
• Stores own side-effects (API calls); components stay declarative.

Async & media views

• This SPA drives streaming/recording UIs (wavesurfer.js, flv.js, WebSocket to the Axum backend). Always tear down players/sockets in onUnmounted to avoid leaks across route changes.
• Guard async-after-unmount: capture an isActive flag or check the component is still mounted before mutating state in a resolved promise.

Anti-patterns to flag in review

• Destructured props/store state (broken reactivity).
• reactive() reassignment, or mixing Options + Composition API.
• Business logic / fetch calls inline in templates or mounted instead of composables/stores.
• Missing cleanup for sockets, intervals, wavesurfer/flv.js instances.
• any, non-null ! abuse, or untyped defineProps/defineEmits.
• Watchers that duplicate what a computed could derive.

Tooling (run from frontend/)

• npm run dev · npm run build · npm run typecheck (tsc) · npm run lint / lint:fix (ESLint) · npm run format (Prettier) · npm test (Vitest).
• Before reviewing a Vue change, prefer gitnexus_query/gitnexus_context (clusters: Pages, Composables, Components) over grepping.