Vue Idioms

Vue Idioms and Patterns

Core Philosophy

Vue 3 Composition API is the default for all new code. <script setup> is the canonical syntax. Think in terms of reactive data flows, not component lifecycle hooks. Composables (use* functions) are the primary unit of logic reuse.

Scope: This file covers Vue 3 coding idioms for components, stores, and composables. For TypeScript type system patterns, see @.agents/skills/typescript-idioms/SKILL.md. For file and folder layout, see references/project-structure.md (and the shared @.agents/skills/frontend-design/references/frontend-layout.md). For test naming, see @.agents/rules/testing-strategy.md. For logging, see @.agents/skills/logging-implementation/SKILL.md.

Loading guard: Do NOT load this skill for non-Vue projects. React → react-idioms; Angular → angular-idioms; Next.js → nextjs-idioms. This skill co-loads with typescript-idioms (required for any Vue work).

When to Load References

Always load typescript-idioms first — it is required alongside this skill for any Vue work. Load these before writing code in the matching context — not after.

Toolchain and Version Milestones

Default to the latest Vue 3 stable. As of July 2026, Vue 3.5+ with Vite 6+.

Key version milestones that affect this skill:

• 3.5+ — useTemplateRef (type-safe template refs), improved useId, Suspense stable
• 3.4+ — defineModel (replaces verbose v-model boilerplate), improved watch generics
• 3.3+ — defineOptions, defineSlots, generic components with <script setup>
• 3.2+ — <script setup> syntax finalized

For recommended package versions and starter configs, see references/recommended-dependencies.md.

<script setup> — The Only Style

Always use <script setup lang="ts">. Never use the Options API or the class-style component pattern for new code.

<!-- ✅ Canonical style -->
<script setup lang="ts">
import { ref, computed } from 'vue';

const props = defineProps<{ title: string; count?: number }>();
const emit = defineEmits<{ 'update:count': [value: number] }>();

const doubled = computed(() => (props.count ?? 0) * 2);
</script>

<!-- ❌ Options API — do not use for new components -->
<script lang="ts">
export default { props: { title: String }, ... }
</script>

Reactivity: ref vs reactive

// ✅ ref for primitives and replaceable objects
const count = ref(0);
const user = ref<User | null>(null);
user.value = fetchedUser; // reassignment is fine

// ✅ reactive for objects where you destructure properties
const form = reactive({ title: '', priority: 'medium' });

// ❌ Never destructure a reactive object — reactivity is lost
const { title } = form; // title is now a plain string, NOT reactive
// ✅ Use toRefs if you must destructure
const { title } = toRefs(form);

Computed Properties

1. Use computed for all derived state — never recompute in the template

   // ✅ Cached, reactive
   const filteredTasks = computed(() =>
       tasks.value.filter(t => t.status === activeFilter.value)
   );
   
   // ❌ Recomputes on every render
   // <template>{{ tasks.filter(t => t.status === filter) }}</template>

2. Never cause side effects inside computed — computed must be pure

   // ❌ Side effect in computed
   const count = computed(() => {
       taskStore.logAccess(); // NO — this is a side effect
       return tasks.value.length;
   });

3. Use writable computed for two-way bindings

   const modelValue = computed({
       get: () => props.modelValue,
       set: (val) => emit('update:modelValue', val),
   });

Watch Strategy

Use the most precise watcher for the situation — over-watching is a performance and correctness problem.

// ✅ watchEffect — auto-tracks dependencies
watchEffect(() => {
    document.title = `Tasks (${count.value})`;
});

// ✅ watch — explicit source, has old value
watch(userId, async (newId, oldId) => {
    if (newId !== oldId) await loadUser(newId);
}, { immediate: true });

// ❌ Avoid using watch just for computed values
watch(tasks, () => { filteredCount.value = tasks.value.filter(...).length; });
// ✅ Use computed instead
const filteredCount = computed(() => tasks.value.filter(...).length);

Pinia Stores

The store directory structure is defined in references/project-structure.md. This section covers Pinia coding idioms.

1. Use the Setup Store API (not Options API) for new stores

   // task/store/task.store.ts
   export const useTaskStore = defineStore('task', () => {
       // State
       const tasks = ref<Task[]>([]);
       const isLoading = ref(false);
   
       // Getters (computed)
       const completedTasks = computed(() =>
           tasks.value.filter(t => t.status === 'done')
       );
   
       // Actions
       async function loadTasks() {
           isLoading.value = true;
           try {
               tasks.value = await taskAPI.getTasks();
           } finally {
               isLoading.value = false;
           }
       }
   
       return { tasks, isLoading, completedTasks, loadTasks };
   });

2. Never mutate store state from outside the store

   // ❌ Direct mutation from a component
   const store = useTaskStore();
   store.tasks.push(newTask); // NO
   
   // ✅ Call an action
   await store.addTask(newTask);

3. Inject the API dependency — never import it directly inside the store

   // ✅ Receives the API interface — testable with createTestingPinia + mock API
   export const useTaskStore = defineStore('task', () => {
       const api = inject<TaskAPI>(TASK_API_KEY);
       if (!api) throw new Error('[TaskStore] TASK_API_KEY not provided — ensure app.provide() is called before store access');
       // ...
   });

4. Use storeToRefs when destructuring a store in components

   // ✅ Preserves reactivity
   const { tasks, isLoading } = storeToRefs(useTaskStore());
   const { loadTasks } = useTaskStore(); // actions don't need storeToRefs

Composables (use* Functions)

Composables are the Vue equivalent of custom hooks — self-contained, reusable units of reactive logic.

1. Naming: always prefix with use

   • useTaskFilters, useAuth, usePagination

2. Return reactive refs, not raw values

   // ✅ Caller can use returned values reactively
   function useCounter(initial = 0) {
       const count = ref(initial);
       const increment = () => count.value++;
       return { count, increment };
   }
   
   // ❌ count is a plain number — not reactive
   function useCounter() {
       let count = 0;
       return { count };
   }

3. Always clean up side effects in onUnmounted

   function useWindowResize() {
       const width = ref(window.innerWidth);
       const handler = () => (width.value = window.innerWidth);
   
       onMounted(() => window.addEventListener('resize', handler));
       onUnmounted(() => window.removeEventListener('resize', handler)); // ✅ cleanup
       return { width };
   }

4. Template refs with useTemplateRef (Vue 3.5+) — type-safe, IDE-friendly replacement for ref(null)

   // ✅ Vue 3.5+ — useTemplateRef provides fully typed access
   const inputEl = useTemplateRef<HTMLInputElement>('myInput');
   // <input ref="myInput" />
   
   // ❌ Old pattern (before 3.5) — less type-safe
   const inputEl = ref<HTMLInputElement | null>(null);

5. Feature-specific composables live inside the feature directory — global composables go in src/composables/. See references/project-structure.md.

Component Design

1. defineProps with TypeScript generics — no runtime validators for typed props

   const props = defineProps<{
       taskId: string;
       variant?: 'compact' | 'full';
   }>();
   
   // Defaults via withDefaults
   const props = withDefaults(defineProps<{ variant?: 'compact' | 'full' }>(), {
       variant: 'full',
   });

2. defineEmits with typed event signatures

   const emit = defineEmits<{
       'update:modelValue': [value: string];
       'submit': [task: CreateTaskRequest];
   }>();

3. defineModel (Vue 3.4+) — preferred v-model pattern

   <script setup lang="ts">
   // ✅ Vue 3.4+ — one line replaces modelValue prop + emit boilerplate
   const modelValue = defineModel<string>({ required: true });
   
   // Named models for multi-v-model components
   const title = defineModel<string>('title');
   const priority = defineModel<'low' | 'medium' | 'high'>('priority', { default: 'medium' });
   </script>
   
   <!-- Usage by parent: <TaskForm v-model="name" v-model:priority="prio" /> -->

   Pre-3.4 fallback (when defineModel is unavailable):

   // ❌ Verbose — use defineModel instead on Vue 3.4+
   const props = defineProps<{ modelValue: string }>();
   const emit = defineEmits<{ 'update:modelValue': [value: string] }>();

4. defineExpose to selectively expose methods to parent refs

   // Everything in <script setup> is private by default.
   // Use defineExpose only for intentional parent access (e.g., form.reset()).
   defineExpose({ reset, focus });
   // ❌ Without defineExpose: parent ref.value.reset() will be undefined

5. v-bind="$attrs" and inheritAttrs: false for forwarding attributes

   // Avoid prop drilling for HTML attributes — forward them to the root element
   defineOptions({ inheritAttrs: false });
   // In template: <input v-bind="$attrs" />

6. One concern per component — if the template exceeds 100 lines (excluding boilerplate), extract a sub-component

7. Never put business logic in the template — computed and composables belong in <script setup>

Template Patterns

1. Always bind :key with stable, unique IDs in v-for — never use index as key when list order can change

   <!-- ✅ Stable key -->
   <TaskCard v-for="task in tasks" :key="task.id" :task="task" />
   
   <!-- ❌ Index key — causes rerender bugs when list reordered -->
   <TaskCard v-for="(task, i) in tasks" :key="i" :task="task" />

2. Never combine v-if and v-for on the same element — wrap with <template>

   <!-- ✅ -->
   <template v-for="task in tasks" :key="task.id">
       <TaskCard v-if="task.visible" :task="task" />
   </template>

Route Transitions

When using <Transition> or <RouterView> with transition effects, CSS frameworks that use @layer (Tailwind v4, Open Props, UnoCSS) can silently break SPA navigation by overriding transition properties in the cascade. This causes transitionend to never fire, permanently blocking the entering component.

1. Avoid mode="out-in" when using @layer-based CSS frameworks — the leaving component's transitionend event may never fire, blocking the entering component indefinitely. Use simultaneous transitions instead:

   <!-- ❌ Dangerous with @layer CSS frameworks -->
   <Transition name="fade" mode="out-in">
     <component :is="Component" />
   </Transition>
   
   <!-- ✅ Safe: simultaneous leave/enter, always mounts new component -->
   <Transition name="fade">
     <component :is="Component" :key="$route.path" />
   </Transition>

2. Always bind :key="$route.path" on dynamic <component> inside <Transition> — forces Vue to treat each route as a distinct component instance, ensuring proper enter/leave lifecycle

3. Use !important on route transition CSS classes — guarantees transition properties win the @layer cascade:

   .fade-enter-active {
     transition: opacity 0.15s ease-in !important;
   }
   .fade-leave-active {
     transition: opacity 0.15s ease-out !important;
     position: absolute !important;
     width: 100% !important;
     top: 0 !important;
     left: 0 !important;
   }
   .fade-enter-from,
   .fade-leave-to {
     opacity: 0 !important;
   }

4. Give the transition parent position: relative — contains the absolutely-positioned leaving element during the simultaneous transition overlap

For full diagnosis steps when a transition-stuck blank screen occurs, see the Debugging Protocol's Frontend module: @.agents/skills/debugging-protocol/languages/frontend.md § CSS × Animation.