/vue-patterns

name: vue-patterns
description: Vue.js 3 Composition API patterns, component architecture, reactivity best practices, Pinia state management, Vue Router navigation, and Nuxt SSR patterns. Activates for Vue, Nuxt, Vite, or Pinia projects. Use when building or reviewing Vue 3, Nuxt, or Pinia code — Composition API, reactivity, or router navigation.
origin: ECC

Vue.js Patterns and Best Practices

Comprehensive guide for Vue.js 3 development using Composition API (`<script setup>`), covering component design, reactivity, state management, routing, testing, and SSR patterns. Nuxt-specific guidance is included where it differs from vanilla Vue.

When to Activate

Activate this skill when:

• The project uses Vue.js (any version), Nuxt, Vite + Vue, or Pinia.
• The user asks about Vue component architecture, composables, reactivity, or state management.
• Reviewing Vue Single-File Components (`.vue` files).
• Setting up Vue Router, Pinia stores, or Vite/Vitest configuration.
• Discussing Vue-specific performance, security, or SSR patterns.

---

1. Project Structure

Recommended Layout (Feature-First)

src/
├── api/              # API client and endpoint definitions
├── assets/           # Static assets (images, fonts, icons)
├── components/       # Shared/reusable components
│   ├── base/         # Base UI primitives (Button, Input, Modal)
│   └── features/     # Feature-specific shared components
├── composables/      # Reusable Composition API logic
├── layouts/          # Page layouts (optional)
├── pages/            # Route-level page components
├── router/           # Vue Router configuration
├── stores/           # Pinia stores
├── types/            # TypeScript type definitions
├── utils/            # Pure utility functions
└── App.vue           # Root component

File Naming

| Convention | When to Use | |-----------|-------------| | `PascalCase.vue` | All components (enforced by `vue/multi-word-component-names`) | | `useCamelCase.ts` | Composables | | `camelCase.ts` | Utilities, API clients, types | | `kebab-case` directories | Route segments, feature folders |

---

2. Component Architecture

Single-File Component Order

<script setup lang="ts">
// 1. Imports (vue → ecosystem → absolute → relative)
// 2. Props & Emits & Slots
// 3. Composables
// 4. Local state (ref/reactive)
// 5. Computed properties
// 6. Methods
// 7. Watchers
// 8. Lifecycle hooks
</script>

<template>
  <!-- Template content -->
</template>

<style scoped>
  /* Scoped styles */
</style>

Presentational vs Container

• **Container components**: Own data fetching, state, and side effects. Render presentational components.
• **Presentational components**: Receive props, emit events. No API calls, no store access. Pure rendering.

Props Best Practices

// Type-based props with defaults
interface Props {
  label: string;
  variant?: "primary" | "secondary";
  disabled?: boolean;
  items: Item[];
}

const props = withDefaults(defineProps<Props>(), {
  variant: "primary",
  disabled: false,
});

• Always provide `type`, and `required`/`default` where appropriate.
• Boolean props: `isXxx`, `hasXxx`, `canXxx`.
• Never mutate props — emit events instead.
• For v-model binding, use `defineModel()` (Vue 3.4+) or `modelValue` + `update:modelValue`.

Events

const emit = defineEmits<{
  submit: [];
  "update:modelValue": [value: string];
  select: [id: string, index: number];
}>();

• Use kebab-case in templates (`@update:model-value`).
• Use camelCase in script (`emit("update:modelValue", val)`).

---

3. Composables (Reusable Logic)

Structure

// composables/useDebounce.ts
export function useDebounce<T>(value: MaybeRef<T>, delay: number): Ref<T> {
  const debounced = ref(toValue(value)) as Ref<T>;

  let timer: ReturnType<typeof setTimeout>;
  watch(
    () => toValue(value),
    (newVal) => {
      clearTimeout(timer);
      timer = setTimeout(() => { debounced.value = newVal; }, delay);
    }
  );

  onUnmounted(() => clearTimeout(timer));
  return readonly(debounced);
}

Rules

• Must start with `use` prefix.
• Return reactive values (`ref`, `computed`, `reactive`), never plain primitives.
• Accept reactive inputs via `MaybeRef` / `toRef()` / `toValue()`.
• Clean up side effects in `onUnmounted` or watcher `onCleanup`.
• No module-scope side effects.

vs Mixins

Composables replace Vue 2 mixins entirely:

• **Mixins**: Opaque data flow, source-of-truth collisions, name conflicts.
• **Composables**: Explicit imports, clear return values, composable and tree-shakable.

---

4. State Management

When to Use What

| Pattern | Use Case | |---------|----------| | `ref()` / `reactive()` | Local component state | | Props + Emits | Parent-child communication | | Provide / Inject | Theme, config, plugin API | | Pinia store | Global, shared, complex state | | Server state composable | API data with caching (wrap `fetch`/TanStack Query) |

Pinia Setup Store (Preferred)

// stores/useCartStore.ts
export const useCartStore = defineStore("cart", () => {
  const items = ref<CartItem[]>([]);
  const isLoading = ref(false);

  const totalPrice = computed(() =>
    items.value.reduce((sum, i) => sum + i.price * i.quantity, 0)
  );
  const itemCount = computed(() =>
    items.value.reduce((sum, i) => sum + i.quantity, 0)
  );

  async function addItem(productId: string) {
    isLoading.value = true;
    try {
      const item = await fetchProduct(productId);
      const existing = items.value.find(i => i.id === item.id);
      if (existing) existing.quantity++;
      else items.value.push({ ...item, quantity: 1 });
    } finally {
      isLoading.value = false;
    }
  }

  return { items, isLoading, totalPrice, itemCount, addItem };
});

• Use Setup Store syntax (not Options Store).
• Prefer actions for business-level mutations and `$patch()` for grouped updates.
• Every async action: handle loading + success + erro