Vue 3 Best Practices

<!-- RIGHT: ProductCard.vue -->
<script setup lang="ts">
interface Props {
  product: Product;
}

const props = defineProps<Props>();
const emit = defineEmits<{ addToCart: [product: Product] }>();
</script>

<template>
  <article class="product-card">
    <h3>{{ product.name }}</h3>
    <span>{{ product.price }}</span>
    <button
      @click="emit('addToCart', product)"
      :aria-label="`Add ${product.name} to cart`"
    >
      Add to cart
    </button>
  </article>
</template>

// RIGHT: composables/useOrders.ts
import { ref, onMounted } from 'vue';

export function useOrders() {
  const orders = ref<Order[]>([]);
  const loading = ref(false);
  const error = ref<string | null>(null);

  async function fetchOrders() {
    loading.value = true;
    error.value = null;           // Clear stale error BEFORE try
    try {
      const res = await fetch('/api/orders');
      if (!res.ok) throw new Error('Failed to load orders');
      const data = await res.json();
      orders.value = data.data;
    } catch (err: any) {
      error.value = err.message;
    } finally {
      loading.value = false;      // Always in finally, not in try
    }
  }

  onMounted(fetchOrders);         // Auto-fetch on mount, NOT inline call

  return { orders, loading, error, reload: fetchOrders };
}

<!-- RIGHT: Usage in component -->
<script setup lang="ts">
const { orders, loading, error, reload } = useOrders();
</script>

<template>
  <p v-if="loading">Loading orders...</p>
  <div v-else-if="error" role="alert">
    {{ error }}
    <button @click="reload" :aria-label="'Retry loading orders'">Retry</button>
  </div>
  <OrderList v-else :orders="orders" />
</template>

// WRONG: Destructuring breaks reactivity
const state = reactive({ count: 0, name: 'Vue' });
const { count, name } = state;  // count and name are now plain values!

// RIGHT: Use ref() for values you'll destructure
const count = ref(0);
const name = ref('Vue');

// RIGHT: Or use toRefs() if you must destructure reactive
const { count, name } = toRefs(state);

// WRONG: Breaks all existing references
let form = reactive({ name: '', email: '' });
form = reactive({ name: 'John', email: 'john@example.com' }); // Broken!

// RIGHT: Mutate properties or use Object.assign
Object.assign(form, { name: 'John', email: 'john@example.com' });

// RIGHT
const count = ref(0);           // Primitive -> ref
const loading = ref(false);     // Primitive -> ref
const error = ref<string | null>(null);  // Primitive/null -> ref
const items = ref<Item[]>([]);  // Array -> ref (preferred)

// computed: For DERIVED VALUES (pure, no side effects)
const fullName = computed(() => `${first.value} ${last.value}`);
const isAdmin = computed(() => user.value?.role === 'admin');

// watch: For SIDE EFFECTS triggered by specific state changes
// USE THIS for: redirects, notifications, API calls, localStorage writes
watch(isAuthenticated, (newVal, oldVal) => {
  if (oldVal && !newVal) {
    router.push('/login');
    showToast('Session expired');
  }
});

// watch with getter for nested property
watch(() => order.value?.status, (newStatus) => {
  if (newStatus === 'ready') showNotification('Order ready!');
});

// watchEffect: For side effects that depend on MULTIPLE reactive sources
// (auto-tracks dependencies, runs immediately)
watchEffect(() => {
  document.title = `${count.value} items in cart`;
});

// WRONG: Options Store syntax
export const useAuthStore = defineStore('auth', {
  state: () => ({ user: null }),
  getters: { isAdmin: (state) => state.user?.role === 'admin' },
  actions: { login(data) { this.user = data; } }
});

// RIGHT: Setup Store syntax
import { ref, computed, watch } from 'vue';
import { defineStore } from 'pinia';

export const useAuthStore = defineStore('auth', () => {
  const user = ref<User | null>(null);
  const isAuthenticated = ref(false);

  // Derived values: use computed()
  const userDisplayLabel = computed(() =>
    user.value ? `${user.value.name} (${user.value.role})` : 'Guest'
  );

  // Actions: plain functions
  function login(userData: User) {
    user.value = userData;
    isAuthenticated.value = true;
  }

  function logout() {
    user.value = null;
    isAuthenticated.value = false;
  }

  // Side effects: use watch(), NOT inside action functions
  watch(isAuthenticated, (newVal, oldVal) => {
    if (oldVal && !newVal) {
      router.push('/login');
      showToast('You have been logged out');
    }
  });

  return { user, isAuthenticated, userDisplayLabel, login, logout };
});

// WRONG: Direct destructure loses reactivity on state/getters
const { user, isAuthenticated, login } = useAuthStore();

// RIGHT: Use storeToRefs for state/getters, direct destructure for actions
import { storeToRefs } from 'pinia';

const authStore = useAuthStore();
const { user, isAuthenticated, userDisplayLabel } = storeToRefs(authStore);
const { login, logout } = authStore;  // Actions don't need storeToRefs

// RIGHT: Template ref pattern
import { ref, onMounted } from 'vue';

const inputEl = ref<HTMLInputElement | null>(null);

onMounted(() => {
  inputEl.value?.focus();
});

<template>
  <input ref="inputEl" />
</template>

<!-- Vue 3.4+ with defineModel (PREFERRED) -->
<script setup lang="ts">
const model = defineModel<string>();
</script>

<template>
  <input :value="model" @input="model = ($event.target as HTMLInputElement).value" />
</template>

<!-- Parent usage -->
<MyInput v-model="searchQuery" />

<!-- Pre-3.4 pattern (still valid) -->
<script setup lang="ts">
const props = defineProps<{ modelValue: string }>();
const emit = defineEmits<{ 'update:modelValue': [value: string] }>();
</script>

<template>
  <input :value="modelValue" @input="emit('update:modelValue', ($event.target as HTMLInputElement).value)" />
</template>