|
| 1 | +--- |
| 2 | +description: 'VueJS 3 development standards and best practices with Composition API and TypeScript' |
| 3 | +applyTo: '**/*.vue, **/*.ts, **/*.js, **/*.scss' |
| 4 | +--- |
| 5 | + |
| 6 | +# VueJS 3 Development Instructions |
| 7 | + |
| 8 | +Instructions for building high-quality VueJS 3 applications with the Composition API, TypeScript, and modern best practices. |
| 9 | + |
| 10 | +## Project Context |
| 11 | +- Vue 3.x with Composition API as default |
| 12 | +- TypeScript for type safety |
| 13 | +- Single File Components (`.vue`) with `<script setup>` syntax |
| 14 | +- Modern build tooling (Vite recommended) |
| 15 | +- Pinia for application state management |
| 16 | +- Official Vue style guide and best practices |
| 17 | + |
| 18 | +## Development Standards |
| 19 | + |
| 20 | +### Architecture |
| 21 | +- Favor the Composition API (`setup` functions and composables) over the Options API |
| 22 | +- Organize components and composables by feature or domain for scalability |
| 23 | +- Separate UI-focused components (presentational) from logic-focused components (containers) |
| 24 | +- Extract reusable logic into composable functions in a `composables/` directory |
| 25 | +- Structure store modules (Pinia) by domain, with clearly defined actions, state, and getters |
| 26 | + |
| 27 | +### TypeScript Integration |
| 28 | +- Enable `strict` mode in `tsconfig.json` for maximum type safety |
| 29 | +- Use `defineComponent` or `<script setup lang="ts">` with `defineProps` and `defineEmits` |
| 30 | +- Leverage `PropType<T>` for typed props and default values |
| 31 | +- Use interfaces or type aliases for complex prop and state shapes |
| 32 | +- Define types for event handlers, refs, and `useRoute`/`useRouter` hooks |
| 33 | +- Implement generic components and composables where applicable |
| 34 | + |
| 35 | +### Component Design |
| 36 | +- Adhere to the single responsibility principle for components |
| 37 | +- Use PascalCase for component names and kebab-case for file names |
| 38 | +- Keep components small and focused on one concern |
| 39 | +- Use `<script setup>` syntax for brevity and performance |
| 40 | +- Validate props with TypeScript; use runtime checks only when necessary |
| 41 | +- Favor slots and scoped slots for flexible composition |
| 42 | + |
| 43 | +### State Management |
| 44 | +- Use Pinia for global state: define stores with `defineStore` |
| 45 | +- For simple local state, use `ref` and `reactive` within `setup` |
| 46 | +- Use `computed` for derived state |
| 47 | +- Keep state normalized for complex structures |
| 48 | +- Use actions in Pinia stores for asynchronous logic |
| 49 | +- Leverage store plugins for persistence or debugging |
| 50 | + |
| 51 | +### Composition API Patterns |
| 52 | +- Create reusable composables for shared logic, e.g., `useFetch`, `useAuth` |
| 53 | +- Use `watch` and `watchEffect` with precise dependency lists |
| 54 | +- Cleanup side effects in `onUnmounted` or `watch` cleanup callbacks |
| 55 | +- Use `provide`/`inject` sparingly for deep dependency injection |
| 56 | +- Use `useAsyncData` or third-party data utilities (Vue Query) |
| 57 | + |
| 58 | +### Styling |
| 59 | +- Use `<style scoped>` for component-level styles or CSS Modules |
| 60 | +- Consider utility-first frameworks (Tailwind CSS) for rapid styling |
| 61 | +- Follow BEM or functional CSS conventions for class naming |
| 62 | +- Leverage CSS custom properties for theming and design tokens |
| 63 | +- Implement mobile-first, responsive design with CSS Grid and Flexbox |
| 64 | +- Ensure styles are accessible (contrast, focus states) |
| 65 | + |
| 66 | +### Performance Optimization |
| 67 | +- Lazy-load components with dynamic imports and `defineAsyncComponent` |
| 68 | +- Use `<Suspense>` for async component loading fallbacks |
| 69 | +- Apply `v-once` and `v-memo` for static or infrequently changing elements |
| 70 | +- Profile with Vue DevTools Performance tab |
| 71 | +- Avoid unnecessary watchers; prefer `computed` where possible |
| 72 | +- Tree-shake unused code and leverage Vite’s optimization features |
| 73 | + |
| 74 | +### Data Fetching |
| 75 | +- Use composables like `useFetch` (Nuxt) or libraries like Vue Query |
| 76 | +- Handle loading, error, and success states explicitly |
| 77 | +- Cancel stale requests on component unmount or param change |
| 78 | +- Implement optimistic updates with rollbacks on failure |
| 79 | +- Cache responses and use background revalidation |
| 80 | + |
| 81 | +### Error Handling |
| 82 | +- Use global error handler (`app.config.errorHandler`) for uncaught errors |
| 83 | +- Wrap risky logic in `try/catch`; provide user-friendly messages |
| 84 | +- Use `errorCaptured` hook in components for local boundaries |
| 85 | +- Display fallback UI or error alerts gracefully |
| 86 | +- Log errors to external services (Sentry, LogRocket) |
| 87 | + |
| 88 | +### Forms and Validation |
| 89 | +- Use libraries like VeeValidate or @vueuse/form for declarative validation |
| 90 | +- Build forms with controlled `v-model` bindings |
| 91 | +- Validate on blur or input with debouncing for performance |
| 92 | +- Handle file uploads and complex multi-step forms in composables |
| 93 | +- Ensure accessible labeling, error announcements, and focus management |
| 94 | + |
| 95 | +### Routing |
| 96 | +- Use Vue Router 4 with `createRouter` and `createWebHistory` |
| 97 | +- Implement nested routes and route-level code splitting |
| 98 | +- Protect routes with navigation guards (`beforeEnter`, `beforeEach`) |
| 99 | +- Use `useRoute` and `useRouter` in `setup` for programmatic navigation |
| 100 | +- Manage query params and dynamic segments properly |
| 101 | +- Implement breadcrumb data via route meta fields |
| 102 | + |
| 103 | +### Testing |
| 104 | +- Write unit tests with Vue Test Utils and Jest |
| 105 | +- Focus on behavior, not implementation details |
| 106 | +- Use `mount` and `shallowMount` for component isolation |
| 107 | +- Mock global plugins (router, Pinia) as needed |
| 108 | +- Add end-to-end tests with Cypress or Playwright |
| 109 | +- Test accessibility using axe-core integration |
| 110 | + |
| 111 | +### Security |
| 112 | +- Avoid using `v-html`; sanitize any HTML inputs rigorously |
| 113 | +- Use CSP headers to mitigate XSS and injection attacks |
| 114 | +- Validate and escape data in templates and directives |
| 115 | +- Use HTTPS for all API requests |
| 116 | +- Store sensitive tokens in HTTP-only cookies, not `localStorage` |
| 117 | + |
| 118 | +### Accessibility |
| 119 | +- Use semantic HTML elements and ARIA attributes |
| 120 | +- Manage focus for modals and dynamic content |
| 121 | +- Provide keyboard navigation for interactive components |
| 122 | +- Add meaningful `alt` text for images and icons |
| 123 | +- Ensure color contrast meets WCAG AA standards |
| 124 | + |
| 125 | +## Implementation Process |
| 126 | +1. Plan component and composable architecture |
| 127 | +2. Initialize Vite project with Vue 3 and TypeScript |
| 128 | +3. Define Pinia stores and composables |
| 129 | +4. Create core UI components and layout |
| 130 | +5. Integrate routing and navigation |
| 131 | +6. Implement data fetching and state logic |
| 132 | +7. Build forms with validation and error states |
| 133 | +8. Add global error handling and fallback UIs |
| 134 | +9. Add unit and E2E tests |
| 135 | +10. Optimize performance and bundle size |
| 136 | +11. Ensure accessibility compliance |
| 137 | +12. Document components, composables, and stores |
| 138 | + |
| 139 | +## Additional Guidelines |
| 140 | +- Follow Vue’s official style guide (vuejs.org/style-guide) |
| 141 | +- Use ESLint (with `plugin:vue/vue3-recommended`) and Prettier for code consistency |
| 142 | +- Write meaningful commit messages and maintain clean git history |
| 143 | +- Keep dependencies up to date and audit for vulnerabilities |
| 144 | +- Document complex logic with JSDoc/TSDoc |
| 145 | +- Use Vue DevTools for debugging and profiling |
| 146 | + |
| 147 | +## Common Patterns |
| 148 | +- Renderless components and scoped slots for flexible UI |
| 149 | +- Compound components using provide/inject |
| 150 | +- Custom directives for cross-cutting concerns |
| 151 | +- Teleport for modals and overlays |
| 152 | +- Plugin system for global utilities (i18n, analytics) |
| 153 | +- Composable factories for parameterized logic |
0 commit comments