.cursorrules (deprecated)

1# Vue 3 Composition API — Cursor Rules
2# Comprehensive rules for Vue 3 development with the Composition API
3 
4## Project Context
5You are working on a Vue 3 application using the Composition API with `<script setup>`
6syntax. The project uses TypeScript, Vite as the build tool, and follows Vue's official
7style guide recommendations. Pinia is used for state management and Vue Router for routing.
8 
9## Tech Stack
10- Vue 3.4+ with `<script setup>` syntax
11- TypeScript (strict mode)
12- Vite for building and dev server
13- Pinia for state management
14- Vue Router 4+ for routing
15- VueUse for composable utilities
16- Vitest + Vue Test Utils for testing
17 
18## Coding Style
19 
20### Naming Conventions
21- Components: PascalCase files matching component name (e.g., `UserProfile.vue`)
22- Composables: camelCase with `use` prefix (e.g., `useAuth.ts`, `useFetchData.ts`)
23- Stores (Pinia): camelCase with `use` prefix and `Store` suffix (e.g., `useUserStore.ts`)
24- Event emits: kebab-case (e.g., `update:modelValue`, `item-selected`)
25- Props: camelCase in script, kebab-case in template
26- Directives: kebab-case with `v-` prefix in template
27- Provide/Inject keys: Symbol constants in a shared file
28 
29### File Structure
30```
31src/
32  components/
33    ui/               # Generic reusable UI components
34    forms/            # Form-related components
35    layout/           # Layout components (Header, Sidebar, Footer)
36  composables/        # Shared composable functions
37  stores/             # Pinia stores
38  views/              # Route page components
39  router/             # Router config and guards
40  types/              # TypeScript type definitions
41  utils/              # Pure utility functions
42  assets/             # Static assets (images, fonts)
43```
44 
45## Component Patterns
46 
47### Single File Component Order
48```vue
49<script setup lang="ts">
50// 1. Type imports
51// 2. Component imports
52// 3. Composable usage
53// 4. Props and emits definitions
54// 5. Reactive state (ref, reactive, computed)
55// 6. Watchers
56// 7. Lifecycle hooks
57// 8. Methods
58</script>
59 
60<template>
61  <!-- Template content -->
62</template>
63 
64<style scoped>
65/* Scoped styles */
66</style>
67```
68 
69### Props and Emits with TypeScript
70```vue
71<script setup lang="ts">
72interface Props {
73  title: string;
74  count?: number;
75  items: Item[];
76  variant?: 'primary' | 'secondary';
77}
78 
79const props = withDefaults(defineProps<Props>(), {
80  count: 0,
81  variant: 'primary',
82});
83 
84const emit = defineEmits<{
85  'update:count': [value: number];
86  'item-click': [item: Item, index: number];
87}>();
88</script>
89```
90 
91### Prefer
92- `<script setup>` over `setup()` function
93- `ref()` for primitives, `reactive()` for objects when destructuring is not needed
94- `computed()` for derived state
95- Composables to share logic between components
96- `defineModel()` for two-way binding (Vue 3.4+)
97- Template refs with `useTemplateRef()` (Vue 3.5+) or `ref<HTMLElement | null>(null)`
98- `v-bind` shorthand and `v-on` shorthand
99- Scoped styles to avoid leaking
100 
101### Avoid
102- Options API in new code (use Composition API exclusively)
103- Mixins — use composables instead
104- `this` keyword (not available in `<script setup>`)
105- Mutating props directly — emit events to parent
106- `reactive()` for primitives (loses reactivity on reassignment)
107- Deeply nested `v-if`/`v-else` chains — use computed or component lookup
108- Global event bus — use Pinia stores or provide/inject
109- Watchers when `computed` would suffice
110 
111## Composable Patterns
112```ts
113// composables/useFetch.ts
114import { ref, watchEffect, type Ref } from 'vue';
115 
116export function useFetch<T>(url: Ref<string> | string) {
117  const data = ref<T | null>(null);
118  const error = ref<Error | null>(null);
119  const isLoading = ref(false);
120 
121  async function execute() {
122    isLoading.value = true;
123    error.value = null;
124    try {
125      const response = await fetch(toValue(url));
126      if (!response.ok) throw new Error(`HTTP ${response.status}`);
127      data.value = await response.json();
128    } catch (e) {
129      error.value = e instanceof Error ? e : new Error(String(e));
130    } finally {
131      isLoading.value = false;
132    }
133  }
134 
135  watchEffect(() => { execute(); });
136 
137  return { data, error, isLoading, refetch: execute };
138}
139```
140 
141## Pinia Store Patterns
142```ts
143// stores/useUserStore.ts
144import { defineStore } from 'pinia';
145import { ref, computed } from 'vue';
146 
147export const useUserStore = defineStore('user', () => {
148  const user = ref<User | null>(null);
149  const isAuthenticated = computed(() => user.value !== null);
150 
151  async function login(credentials: LoginCredentials) {
152    user.value = await authApi.login(credentials);
153  }
154 
155  function logout() {
156    user.value = null;
157  }
158 
159  return { user, isAuthenticated, login, logout };
160});
161```
162 
163## Error Handling
164- Use `onErrorCaptured()` lifecycle hook for component-level error boundaries
165- Handle async errors in composables and expose error state via refs
166- Use Vue Router `onBeforeRouteLeave` to prevent unsaved data loss
167- Provide user-friendly error messages in the UI
168- Type error states explicitly
169 
170## Testing
171- Use Vitest with `@vue/test-utils` for component testing
172- Mount components with `mount()` for full rendering, `shallowMount()` for isolation
173- Test composables independently by wrapping in a test component
174- Mock Pinia stores with `createTestingPinia()`
175- Test async behavior with `await flushPromises()`
176- Prefer testing user-visible behavior over internal state
177 
178## Performance Guidelines
179- Use `v-once` for static content that never changes
180- Use `v-memo` for expensive list rendering that rarely updates
181- Use `defineAsyncComponent()` for lazy-loaded components
182- Use `<KeepAlive>` for caching expensive component trees
183- Use `shallowRef()` for large objects where deep reactivity is unnecessary
184- Avoid expensive operations in computed — they re-run on every dependency change
185- Use virtual scrolling for large lists (`vue-virtual-scroller`)
186 
187## Common Pitfalls
188- Destructuring `reactive()` objects loses reactivity — use `toRefs()` or keep as object
189- Forgetting `.value` when accessing `ref()` in script (not needed in template)
190- Watching a getter instead of a ref: `watch(() => state.count, ...)` vs `watch(countRef, ...)`
191- Not using `toValue()` / `unref()` in composables to accept both refs and plain values
192- Creating watchers without cleanup in composables used outside components
193- Using `v-if` and `v-for` on the same element (v-if has higher priority in Vue 3)
194- Forgetting `key` attribute on `<component :is>` to force re-mount on type change
195- Not marking raw large objects with `markRaw()` when reactivity is unnecessary
196