vue-nuxt-best-practices: Instructions file for Codex

Vue3 & Nuxt4 Best Practices

57 performance optimization rules for Vue3 and Nuxt4 applications. Designed for AI coding agents to automatically apply best practices.

Quick Reference

Priority	Category	Rules
Critical	SSR & Hydration	8
Critical	Data Fetching	7
High	Reactivity	8
High	Component Design	7
Medium	Performance	8
Medium	State Management	6
Low	Bundle Optimization	7
Low	Nuxt Specific	6

---

SSR & Hydration

[CRITICAL] Avoid Hydration Mismatch

Inconsistent rendering results between server and client cause hydration warnings and potential bugs.

Bad Example:

<template>
  <div>{{ Date.now() }}</div>
  <div>{{ Math.random() }}</div>
</template>

Good Example:

<template>
  <ClientOnly>
    <div>{{ currentTime }}</div>
  </ClientOnly>
</template>

<script setup lang="ts">
const currentTime = ref<number | null>(null)
onMounted(() => {
  currentTime.value = Date.now()
})
</script>

---

[CRITICAL] Use ClientOnly Component Correctly

Some components can only run on the client side (e.g., ECharts, map components).

<template>
  <ClientOnly>
    <VChart :option="chartOption" />
    <template #fallback>
      <ChartSkeleton />
    </template>
  </ClientOnly>
</template>

---

[CRITICAL] Use onMounted for Browser APIs

Directly accessing browser APIs at the top level of <script setup> causes SSR errors.

Bad:

const width = window.innerWidth // SSR error

Good:

const width = ref(0)
onMounted(() => {
  width.value = window.innerWidth
})

---

[HIGH] Use import.meta.client for Conditional Logic

if (import.meta.client) {
  // Client-side only execution
  initAnalytics()
}

if (import.meta.server) {
  // Server-side only execution
}

---

Data Fetching

[CRITICAL] Use useFetch Instead of $fetch

$fetch causes duplicate data fetching.

Bad:

const data = await $fetch('/api/users')