Project: [App Name]

Commands

npm run dev        # Start Vite dev server
npm run build      # Production build (runs tsc + vite build)
npm run preview    # Preview production build locally
npm run test       # Run Vitest unit tests
npm run lint       # ESLint check
npm run typecheck  # Run tsc --noEmit

Stack

• Vue 3 with Composition API (<script setup> only — no Options API)
• TypeScript 5, strict mode enabled
• Vite for bundling and dev server
• Vue Router 4 for client-side routing
• Pinia for global state management
• VueUse for composable utilities
• Vitest + Vue Test Utils for unit tests

Project Structure

src/
├── assets/          # Static assets (images, fonts, global CSS)
├── components/      # Shared UI components (PascalCase filenames)
├── composables/     # Reusable logic hooks (useXxx.ts)
├── layouts/         # Page layout wrappers
├── pages/           # Route-level components (maps to router)
├── router/          # Vue Router config (index.ts)
├── stores/          # Pinia stores (useXxxStore.ts)
├── types/           # Shared TypeScript interfaces and types
└── utils/           # Pure helper functions (no Vue/component deps)

Conventions

Detailed patterns with code examples live in .claude/rules/. The summary below is the quick reference that applies on every turn.

Components

• All component files use PascalCase: UserCard.vue, BaseButton.vue
• Always use <script setup lang="ts"> — never Options API or defineComponent
• Define props and emits with defineProps<{}>() and defineEmits<{}>()
• Use defineModel() for two-way bindings instead of manual prop+emit patterns
• Prefix generic reusable components with Base: BaseInput, BaseModal
• Prefix layout components with The for singletons: TheHeader, TheSidebar

TypeScript

• Prefer interface over type for object shapes
• Never use enum — use as const maps instead
• No any — use unknown and narrow explicitly
• Strict mode is on: unused variables and implicit returns are errors

State Management

• All Pinia stores use the Setup Store syntax (not Options Store)
• Store files are named useXxxStore.ts and live in src/stores/
• Keep server-fetched data in stores; keep local UI state in components
• Always destructure store state with storeToRefs — plain destructuring breaks reactivity

Composables

• All composables are prefixed with use: useAuth.ts, useNotification.ts
• Live in src/composables/ — never inline reusable logic inside components
• Prefer VueUse primitives (useLocalStorage, useFetch, etc.) over custom re-implementations

Routing

• Route names use kebab-case strings: 'user-profile', 'settings-account'
• Lazy-load all page components: component: () => import('@/pages/UserPage.vue')
• Route meta types are declared in src/router/index.ts via RouteMeta interface extension

Styling

• Scoped styles by default: <style scoped>
• Use CSS custom properties for theming; avoid hardcoded color/size values in components
• Utility classes (if using Tailwind) are preferred over component-scoped styles for layout

Imports

• Always use the @/ alias for src/ — never use relative ../../ paths across feature boundaries
• Named exports everywhere; default exports only for .vue components (Vue convention)

Error Handling

• Never swallow errors silently — always log or surface them
• Use a central error handler composable (useErrorHandler) instead of scattered try/catch
• Do not expose raw error messages or stack traces to the UI

Watch Out For

• tsc --noEmit runs as part of npm run build. Fix type errors before building — Vite does not block on them during dev
• Vue Router <RouterView> requires a matching named route or it renders nothing silently
• Pinia stores are not available before app.use(pinia) — never call stores at module top level
• defineProps and defineEmits must use the generic syntax in <script setup> for proper type inference
• VueUse composables require the component instance context — do not call them inside plain .ts utility files