feat(rules): add Vue coding-style and composables/reactivity rules

Add rules/vue/coding-style.md: - <script setup> Composition API enforcement - Naming conventions (PascalCase components, useCamelCase composables) - SFC structure order, props/emits/slots patterns - Vue 3.5+ reactive props destructure with native default values - Template conventions, import ordering Add rules/vue/hooks.md: - ref() vs reactive() guidance and replacement pitfalls - Vue 3.5+ reactive props destructure (version-specific: Vue<3.5 loses reactivity, 3.5+ reactive by default with watch limitation) - computed() purity rules, watch vs watchEffect comparison - Watcher cleanup with onWatcherCleanup() (Vue 3.5+) and onCleanup callback - useTemplateRef() (Vue 3.5+) replacing name-matched plain refs - Composable conventions (use prefix, reactive returns, MaybeRef inputs) - shallowRef/shallowReactive for large data structures
2026-06-16 08:26:52 +08:00 · 2026-06-12 17:53:28 +08:00 · 2026-06-12 17:53:28 +08:00 · 57386e156d
commit 57386e156d
parent 6bde9be36c
2 changed files with 576 additions and 0 deletions
--- a/rules/vue/coding-style.md
+++ b/rules/vue/coding-style.md
@ -0,0 +1,214 @@
+---
+paths:
+  - "**/*.vue"
+  - "**/components/**/*.ts"
+  - "**/components/**/*.js"
+  - "**/composables/**/*.ts"
+  - "**/composables/**/*.js"
+---
+# Vue Coding Style
+
+> This file extends [typescript/coding-style.md](../typescript/coding-style.md) and [common/coding-style.md](../common/coding-style.md) with Vue-specific conventions. For composable rules see [hooks.md](./hooks.md).
+
+## API Style
+
+- Use `<script setup>` Composition API for all new Vue 3 components.
+- Options API is acceptable only when maintaining a legacy Vue 2 / early Vue 3 codebase.
+- Mixins are forbidden in new code — replace with composables.
+- `<script setup lang="ts">` for all TypeScript projects.
+
+## File Extensions
+
+- `.vue` for Single-File Components
+- `.ts` for composables, stores, utilities, router config, type definitions
+- `.test.ts` mirroring the source file
+- `.cy.ts` for Cypress component tests
+
+## Naming
+
+| Entity | Convention | Example |
+|--------|-----------|---------|
+| Component files | PascalCase or kebab-case (team convention) | `UserCard.vue` or `user-card.vue` |
+| Component name | `PascalCase` (multi-word, enforced by `vue/multi-word-component-names`) | `UserCard`, `BaseButton` |
+| Composables | `useCamelCase` | `useUser`, `useDebounce` |
+| Pinia stores | `useCamelCaseStore` | `useUserStore`, `useCartStore` |
+| Props | camelCase in `<script>`, kebab-case in templates | `userName` / `user-name` |
+| Events | kebab-case in templates | `@update:model-value`, `@item-selected` |
+| Boolean props | `isXxx`, `hasXxx`, `canXxx`, `shouldXxx` | `isLoading`, `hasError`, `canSubmit` |
+
+## Component Shape
+
+```vue
+<script setup lang="ts">
+// 1. Imports
+import { ref, computed, onMounted } from "vue";
+import { useUser } from "@/composables/useUser";
+import UserAvatar from "./UserAvatar.vue";
+
+// 2. Props & Emits
+const props = defineProps<{
+  userId: string;
+  showAvatar?: boolean;
+}>();
+
+const emit = defineEmits<{
+  select: [id: string];
+}>();
+
+// 3. Composables
+const { user, isLoading } = useUser(() => props.userId);
+
+// 4. Local state
+const isExpanded = ref(false);
+
+// 5. Computed
+const displayName = computed(() =>
+  user.value ? `${user.value.firstName} ${user.value.lastName}` : "Unknown"
+);
+
+// 6. Methods
+function handleSelect() {
+  emit("select", props.userId);
+}
+
+// 7. Lifecycle hooks
+onMounted(() => {
+  console.log("UserCard mounted");
+});
+</script>
+
+<template>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else>
+    <UserAvatar :src="user?.avatar" />
+    <span>{{ displayName }}</span>
+    <button @click="handleSelect">Select</button>
+  </div>
+</template>
+```
+
+## Single-File Component Structure
+
+Enforce this order inside `.vue` files:
+
+1. `<script setup>` (or `<script>`)
+2. `<template>`
+3. `<style scoped>` (or `<style module>`)
+
+Use block comments (`/* */`) inside `<script>`, HTML comments (`<!-- -->`) inside `<template>`.
+
+## Props
+
+- Prefer `defineProps<>()` type-based declaration with TypeScript.
+- **Vue 3.5+**: Reactive Props Destructure is stabilized — you can destructure `defineProps()` and the variables are automatically reactive. Use JavaScript native default values syntax:
+  ```ts
+  const { count = 0, msg = "hello" } = defineProps<{ count?: number; msg?: string }>();
+  ```
+- **Vue < 3.5**: Use `withDefaults()` for typing props with default values, or access via `props.xxx`. Never destructure (captures snapshot).
+- Never mutate props — use `defineEmits` for upward communication.
+- Group related props into a single object type when they represent a logical entity.
+
+```vue
+<!-- Vue 3.5+: native defaults with destructuring -->
+<script setup lang="ts">
+const { user, variant = "primary", disabled = false } = defineProps<{
+  user: User;
+  variant?: "primary" | "secondary";
+  disabled?: boolean;
+}>();
+</script>
+
+<!-- Vue < 3.5: withDefaults -->
+<script setup lang="ts">
+interface Props {
+  user: User;
+  variant?: "primary" | "secondary";
+  disabled?: boolean;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  variant: "primary",
+  disabled: false,
+});
+</script>
+```
+
+## Emits
+
+- Use type-based `defineEmits<>()` with TypeScript payload signatures.
+- Keep event names in kebab-case in templates, camelCase in script.
+
+```vue
+<script setup lang="ts">
+const emit = defineEmits<{
+  "update:modelValue": [value: string];
+  submit: [];
+  cancel: [];
+}>();
+</script>
+```
+
+## Slots
+
+- Type slots explicitly with `defineSlots<>()` for TypeScript projects.
+- Document slot purpose and expected props in a comment above template usage.
+
+```vue
+<script setup lang="ts">
+defineSlots<{
+  default: (props: { item: Item }) => any;
+  header: () => any;
+  footer: () => any;
+}>();
+</script>
+```
+
+## Template Conventions
+
+- Self-close tags with no children: `<UserAvatar :src="url" />`
+- Use `<template>` for conditional groups, not wrapper `<div>`.
+- `v-if` / `v-else-if` / `v-else` must be on consecutive sibling elements.
+- Never put multi-line logic inline in templates — extract to computed or method.
+
+```vue
+<!-- Prefer -->
+<h1>{{ greeting }}</h1>
+
+<!-- Over -->
+<h1>{{ user.isAdmin ? "Welcome, admin" : `Hello ${user.name}` }}</h1>
+```
+
+## Imports
+
+- Vue imports first: `import { ref, computed } from "vue"`
+- Then ecosystem packages (vue-router, pinia), then absolute project imports, then relative
+- Type-only imports: `import type { User } from "@/types"`
+- Auto-imported functions (Nuxt, unplugin-auto-import) must still be explicitly imported when the project does not use auto-import.
+
+## Script vs Template
+
+- Keep `<script setup>` as the logic owner — templates should contain only rendering directives.
+- Composable returns keep naming consistent: `const { user, isLoading } = useUser(id)` — destructured for readability.
+- No side effects in `computed()` getters — they must be pure.
+
+## Class Components
+
+Forbidden in new code. The `vue-class-component` and `vue-property-decorator` libraries are deprecated. Migrate to Composition API.
+
+## File Layout per Component
+
+```
+components/UserCard/
+  UserCard.vue
+  UserCard.test.ts
+  index.ts             # re-export for barrel pattern
+```
+
+Or co-located:
+
+```
+components/UserCard.vue
+components/__tests__/UserCard.test.ts
+```
+
+Follow the project's existing convention. Inline single-file components are fine for trivial presentational pieces.
--- a/rules/vue/hooks.md
+++ b/rules/vue/hooks.md
@ -0,0 +1,362 @@
+---
+paths:
+  - "**/*.vue"
+  - "**/composables/**/*.ts"
+  - "**/composables/**/*.js"
+  - "**/use-*.ts"
+  - "**/use-*.js"
+---
+# Vue Composables and Reactivity
+
+> This file covers **Vue composables** (`use*()`, `ref()`, `reactive()`, `computed()`, `watch()`, `watchEffect()`). Named to match the per-language convention `rules/<lang>/hooks.md`.
+>
+> Extends [typescript/patterns.md](../typescript/patterns.md) and [common/patterns.md](../common/patterns.md).
+
+## Reactivity Fundamentals
+
+### `ref()` vs `reactive()`
+
+- Use `ref()` for primitives and for values that will be replaced wholesale.
+- Use `reactive()` for object structures whose properties are mutated individually.
+- In practice, `ref()` is preferred as the default — it's explicit, works everywhere, and avoids the pitfalls of `reactive()` (no replacement, no destructuring).
+
+```ts
+// ref — universal, explicit .value
+const count = ref(0);
+const user = ref<User | null>(null);
+
+// reactive — only for objects, no .value
+const form = reactive({ email: "", password: "" });
+```
+
+### Props Destructuring (Version-Specific)
+
+**Vue 3.5+**: Reactive Props Destructure is stabilized and enabled by default. Destructured variables from `defineProps()` are automatically reactive — the compiler transforms `count` to `props.count` at compile time.
+
+```vue
+<script setup lang="ts">
+// Vue 3.5+: CORRECT — destructured props are reactive
+const { userId, userName } = defineProps<{ userId: string; userName: string }>();
+// userId and userName track the parent's prop updates
+
+// Native default values (Vue 3.5+)
+const { count = 0, msg = "hello" } = defineProps<{
+  count?: number;
+  msg?: string;
+}>();
+```
+
+**Vue < 3.5**: Destructuring captures snapshot values at setup time — they won't update.
+
+```vue
+<script setup lang="ts">
+// Vue < 3.5: WRONG: destructured props lose reactivity
+const { userId, userName } = defineProps<{ userId: string; userName: string }>();
+
+// Vue < 3.5: CORRECT: access via props.xxx
+const props = defineProps<{ userId: string; userName: string }>();
+// In methods/computed: props.userId
+
+// ALSO CORRECT: toRefs for individual refs
+const { userId, userName } = toRefs(props);
+</script>
+```
+
+**Important limitation (all Vue 3.5+ versions)**: You cannot `watch()` a destructured prop variable directly — must wrap in a getter:
+
+```ts
+// WRONG: direct watch on destructured prop (compile-time error in Vue 3.5+)
+watch(count, (newVal) => { ... });
+
+// CORRECT: getter wrapper
+watch(() => count, (newVal) => { ... });
+```
+
+When passing a destructured prop to a composable that needs reactivity, wrap in a getter and use `toValue()` inside the composable:
+
+```ts
+useDynamicCount(() => count); // ✅ preserves reactivity
+```
+
+### Replacing reactive() Objects
+
+```ts
+// WRONG: breaks reactivity
+let state = reactive({ a: 1, b: 2 });
+state = reactive({ a: 3, b: 4 }); // new object, old watchers lost
+
+// CORRECT: mutate in place
+Object.assign(state, { a: 3, b: 4 });
+
+// BETTER: use ref for values that get replaced
+const state = ref({ a: 1, b: 2 });
+state.value = { a: 3, b: 4 }; // reactivity preserved
+```
+
+### `.value` in Script vs Template
+
+```vue
+<script setup>
+const count = ref(0);
+// Inside script: MUST use .value
+console.log(count.value);
+function increment() { count.value++; }
+</script>
+
+<template>
+  <!-- Inside template: NO .value (auto-unwrapped) -->
+  <span>{{ count }}</span>
+  <button @click="count++">Increment</button>
+</template>
+```
+
+## `computed()` Rules
+
+- Computed getters must be pure — no side effects (no state mutation, API calls, DOM writes).
+- Never mutate other state inside a computed getter.
+- Computed setter must be paired with a getter — don't create write-only computeds.
+
+```ts
+// CORRECT: pure getter
+const fullName = computed(() => `${firstName.value} ${lastName.value}`);
+
+// CORRECT: with setter
+const fullName = computed({
+  get: () => `${firstName.value} ${lastName.value}`,
+  set: (val: string) => {
+    const [first, last] = val.split(" ");
+    firstName.value = first;
+    lastName.value = last;
+  },
+});
+
+// WRONG: side effect in computed
+const displayName = computed(() => {
+  analytics.track("name-computed"); // ❌ side effect
+  return user.value.name;
+});
+```
+
+## `watch()` vs `watchEffect()`
+
+| Feature | `watch()` | `watchEffect()` |
+|---------|-----------|-----------------|
+| Explicit source | Yes — declare what to track | No — auto-tracks dependencies |
+| Access to old/new values | Yes | No |
+| Initial run | Optional (`immediate: true`) | Always runs immediately |
+| Use case | Side effect on specific data change | Sync reactive state to external system |
+
+```ts
+// watch: explicit, has old/new
+watch(
+  () => props.userId,
+  (newId, oldId) => {
+    fetchUser(newId);
+  }
+);
+
+// watchEffect: auto-tracking, immediate
+watchEffect(() => {
+  console.log(`User ${userId.value} is ${status.value}`);
+});
+```
+
+## Watcher Source Pitfalls
+
+```ts
+// WRONG: watching a ref object (never changes)
+const u = ref({ name: "Alice" });
+watch(u, (val) => {}); // ❌ watches the ref wrapper, not the value
+
+// CORRECT: getter returning .value
+watch(() => u.value, (val) => {});
+
+// ALSO WRONG: reactive getter that doesn't track
+watch(() => state.name, (val) => {}); // ❌ val is snapshot at setup
+
+// CORRECT: getter that accesses property on reactive object
+watch(() => state.name, (val) => {}); // ✅ .name access inside getter is tracked
+// Wait — careful: `() => state.name` DOES track correctly because the getter
+// accesses `.name` on the reactive proxy. The getter is re-evaluated by Vue.
+
+// ACTUALLY WRONG case: direct reactive property
+watch(state.name, ...); // ❌ state.name evaluates to a primitive, not trackable
+
+// CORRECT: getter returning reactive property
+watch(() => state.name, (newName) => { ... });
+```
+
+## Cleanup
+
+Every watcher that creates subscriptions, intervals, or fetch requests must clean up.
+
+**Vue 3.5+**: Use `onWatcherCleanup()` (globally importable from `vue`) for watcher-side-effect cleanup:
+
+```ts
+import { watch, onWatcherCleanup } from "vue";
+
+watch(userId, async (newId) => {
+  const controller = new AbortController();
+  onWatcherCleanup(() => controller.abort());
+  const data = await fetch(`/api/users/${newId}`, { signal: controller.signal });
+  user.value = await data.json();
+});
+```
+
+**All Vue 3 versions**: The watcher callback also receives an `onCleanup` parameter:
+
+```ts
+// watch callback receives an onCleanup function
+watch(userId, async (newId, _oldId, onCleanup) => {
+  const controller = new AbortController();
+  onCleanup(() => controller.abort());
+  const data = await fetch(`/api/users/${newId}`, { signal: controller.signal });
+  user.value = await data.json();
+});
+
+// watchEffect also receives onCleanup
+watchEffect((onCleanup) => {
+  const id = setInterval(tick, 1000);
+  onCleanup(() => clearInterval(id));
+});
+```
+
+## `useTemplateRef()` (Vue 3.5+)
+
+Use `useTemplateRef()` instead of matching a plain `ref` variable name to the template `ref` attribute. It supports dynamic ref IDs and provides better type safety.
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef } from "vue";
+
+// Static ref
+const inputEl = useTemplateRef<HTMLInputElement>("input");
+
+// Dynamic ref
+const refId = ref("input");
+const dynamicEl = useTemplateRef<HTMLInputElement>(refId);
+</script>
+
+<template>
+  <input ref="input" type="text" />
+</template>
+```
+
+- The string passed to `useTemplateRef()` must match the `ref` attribute value in the template, **not** the variable name.
+- `@vue/language-tools` 2.1+ provides auto-completion and warnings for `useTemplateRef`.
+
+## Composable Conventions
+
+### Must start with `use`
+
+```ts
+// CORRECT
+export function useDebounce<T>(value: Ref<T>, delay: number): Ref<T> { ... }
+
+// WRONG
+export function debounce<T>(value: Ref<T>, delay: number): Ref<T> { ... }
+```
+
+### Return reactive values
+
+Composables must return `ref()` / `computed()` / `reactive()` so the consumer stays reactive. Never return a raw primitive or plain object snapshot.
+
+```ts
+// CORRECT
+export function useCounter() {
+  const count = ref(0);
+  const doubled = computed(() => count.value * 2);
+  function increment() { count.value++; }
+  return { count, doubled, increment };
+}
+
+// WRONG: returns snapshot
+export function useCounter() {
+  let count = 0;
+  function increment() { count++; }
+  return { count, increment }; // count is a plain number — not reactive
+}
+```
+
+### Accept reactive inputs gracefully
+
+When a composable accepts reactive data, use `toRef()` / `toValue()` (Vue 3.3+) so callers can pass either a ref or a plain value.
+
+```ts
+export function useTitle(newTitle: MaybeRef<string>) {
+  const title = toRef(newTitle);
+  watchEffect(() => {
+    document.title = title.value;
+  });
+}
+
+// Caller can pass either:
+useTitle("Home");         // plain value
+useTitle(ref("Home"));    // ref
+useTitle(computed(...));  // computed
+```
+
+### Side effects must be scoped
+
+Composables that create side effects (event listeners, timers, subscriptions) must:
+
+1. Only run when the component using them is mounted — use `onMounted` / `watch`.
+2. Clean up automatically — use `onUnmounted` or watcher `onCleanup`.
+
+```ts
+export function useEventListener<K extends keyof WindowEventMap>(
+  event: K,
+  handler: (e: WindowEventMap[K]) => void,
+) {
+  onMounted(() => window.addEventListener(event, handler));
+  onUnmounted(() => window.removeEventListener(event, handler));
+}
+```
+
+### No module-scope side effects
+
+Never initialize state, start timers, or subscribe to external systems in the module scope of a composable file — it runs once regardless of component instance count.
+
+```ts
+// WRONG: module scope side effect
+const globalCount = ref(0); // ❌ shared across all components
+setInterval(() => globalCount.value++, 1000);
+
+export function useGlobalCount() {
+  return globalCount;
+}
+
+// CORRECT: scoped to each invocation
+export function useInterval(fn: () => void, ms: number) {
+  onMounted(() => {
+    const id = setInterval(fn, ms);
+    onUnmounted(() => clearInterval(id));
+  });
+}
+```
+
+## `shallowRef()` and `shallowReactive()`
+
+Use `shallowRef()` for large immutable data structures that are replaced as a whole — avoids the deep reactivity overhead.
+
+```ts
+const items = shallowRef<Item[]>([]);
+// items.value = await fetchItems(); // replacement works
+// items.value[0].name = "new";     // ❌ inner mutations are NOT reactive
+```
+
+Use `shallowReactive()` when only top-level properties should be reactive.
+
+## Lint Configuration
+
+Required rules:
+
+```json
+{
+  "rules": {
+    "vue/no-ref-as-operand": "error",
+    "vue/no-mutating-props": "error",
+    "vue/return-in-computed-property": "error"
+  }
+}
+```