neo-vue

Modern Vue 3 & Pinia Development Expert (neo-vue)

This skill provides agents with development and review guidelines for Vue 3 (Composition API) and Pinia state management. It helps produce code that conforms to Vue Style Guide priority A/B rules, avoid common reactivity pitfalls, and generate consistent, strongly typed Single-File Components (SFC).

Gotchas

• Destructuring reactive objects causes loss of reactivity: Directly destructuring props or objects defined by reactive() is prohibited (for example:const { name } = props or const { x } = state), as this completely loses Vue reactivity tracking!
  • Error prevention mechanism: You must use toRefs(props) or toRef(props, 'name') to preserve its reactivity.
• Destructuring a Pinia Store causes loss of state reactivity: Directly destructuring a Pinia store's state (such as const { user } = useAuthStore()) causes the state to lose two-way reactivity!
  • Error prevention mechanism: You must use storeToRefs(store) to destructure state; actions, however, can be destructured directly and normally.
• Manual and cumbersome v-model binding: Before Vue 3.4, custom two-way binding required manually declaring the modelValue prop and emitting the update:modelValue event, which is prone to mistakes.
  • Error prevention mechanism: In Vue 3.4+ projects, preferentially use the defineModel() macro to declare two-way binding, reducing the risk of inconsistency between props and events.
• Mixing v-if and v-for on the same node: In Vue 3,v-if has higher priority than v-for, which means the v-if conditional checkcannotaccess variables in the v-for loop, and will directly cause compile-time or runtime errors!
  • Error prevention mechanism: Always use the <template> tag to wrap v-for, then use v-ifinside the child node, or use a computed computed property in advance to filter the array.

Workflow Checklist

Progress:

• Step 1: Perceive Setup & Tooling
• Step 2: Load Guides & Best Practices
• Step 3: Reasoning & Architecture
• Step 4: Generate SFC & Stores
• Step 5: Code Quality Review

---

Detailed Guidelines

Step 1 — Perceive Setup & Tooling (Perceive)

1. Check dependency configuration: Read package.json, determine the Vue version (confirm it is Vue 3.x) and whether pinia、vue-router。
2. Identify the build tool and language: Confirm whether it is a Vite project, and whether TypeScript (lang="ts") and Scoped CSS are enabled.

Step 2 — Load Coding Standards & Pitfall Guide (Reason)

Before performing Vue 3 development or review,the deep knowledge base must be dynamically loaded：

1. Read references/coding-style.md to confirm official priority conventions such as component naming (must be multi-word PascalCase), prop definitions, etc.
2. Read references/anti-patterns.md to avoid anti-patterns such as props mutation and computed side effects.
3. Read references/patterns.md to achieve reasonable splitting of Composables and architectural design of Pinia Setup Stores.

Step 3 — Architectural Reasoning and Reactivity Planning (Reason)

Before writing code, first consider the following design:

1. Reactivity choice: Unless it is a complex object where multiple properties need to be highly interrelated, otherwiseprefer using ref() instead of reactive(), to ensure consistency when accessing .value and avoid destructuring deactivation.
2. State sinking: Evaluate whether the state belongs to component-local state (use ref) or global state (use Pinia Setup Store）。

Step 4 — Apply templates to generate consistent code (Act)

1. SFC structure: Newly created components must use the <script setup> syntax, and according to project settings prioritize adding lang="ts"。
2. Apply templates: Read and refer to assets/Vue3SFCComponentTemplate.vue as a layout example for a standard Vue 3 component.
3. Mandatory language and style: All code comments and explanations must use Traditional Chinese (Taiwan). Terminology must be aligned (for example: component, property, state management, reactivity, two-way binding, computed property).

Step 5 — Code health check and self-proofreading (Act)

1. Confirm that no Side Effects such as state modification or API calls are performed in computed .
2. Confirm that no direct assignment or modification is made to props .
3. Confirm that the v-for binding of key uses a stable unique ID, rather than the array index index。

---

Output Templates

When generating a new component, output according to the following consistent structure; for more implementation details, please refer to assets/Vue3SFCComponentTemplate.vue：

<template>
  <div class="vue-expert-component">
    <!-- 模板內容 -->
  </div>
</template>

<script setup lang="ts">
import { ref, computed } from 'vue';

// 1. 定義屬性與事件 (Props, Emits, Models)
const props = defineProps<{
  title: string;
}>();

const emit = defineEmits<{
  (e: 'change', value: string): void;
}>();

// Vue 3.4+ 雙向綁定巨集
const modelValue = defineModel<string>();

// 2. 狀態定義 (State)
const count = ref(0);

// 3. 計算屬性 (Computed)
const doubleCount = computed(() => count.value * 2);

// 4. 方法定義 (Methods)
function handleAction() {
  emit('change', 'action-triggered');
}
</script>

<style scoped>
/* 必須使用 scoped 以免全域樣式污染，並優先選用 class 選擇器 */
.vue-expert-component {
  display: flex;
  flex-direction: column;
}
</style>