Vue Guidelines

This document outlines best practices for building robust, maintainable, and modern Vue.js applications using the Composition API and TypeScript.

1. General Principles

• Composition API: Always use the Composition API with <script setup lang="ts">.
• Single File Components (SFC): Keep template, script, and style in one file.
• Structure: Order blocks as <script setup>, <template>, <style>.
• Naming: Use PascalCase for component filenames (e.g., MyComponent.vue).

2. TypeScript Integration

• Strict Typing: Enable strict mode in tsconfig.json. Avoid any.

• Props: Use defineProps with type-only declarations for better inference.

  <script setup lang="ts">
  interface Props {
    msg: string
    count?: number
  }
  
  // withDefaults is optional but recommended for default values
  const props = withDefaults(defineProps<Props>(), {
    count: 0
  })
  </script>
  

• Emits: Use defineEmits with type-only declarations.

  <script setup lang="ts">
  const emit = defineEmits<{
    (e: 'update', value: number): void
    (e: 'close'): void
  }>()
  </script>
  

3. Reactivity Fundamentals

• ref vs reactive: Prefer ref for most cases, especially for primitives and when you need to replace the entire object. Use reactive sparingly for grouped state where structure matters.

• Unwrapping: Remember .value is required in <script> but unwrapped in <template>.

• Destructuring: Be careful destructuring reactive objects; use toRefs to maintain reactivity.

  const state = reactive({ count: 0 })
  const { count } = toRefs(state) // count is now a Ref
  

4. Component Patterns

• Composables: Extract logic into reusable composables (use... functions). Start with use.

  // useCounter.ts
  export function useCounter() {
    const count = ref(0)
    const increment = () => count.value++
    return { count, increment }
  }
  

• Slots: Use slots for flexible content injection. Named slots for multiple insertion points.

• Provide/Inject: Use for deep prop drilling, but prefer explicit props for direct parent-child communication. Key injection symbols to avoid collisions.

• Splitting components: Split components into smaller, focused components to improve maintainability and reusability. A components should't do too many things at once. Also if you feel the need to start adding comments for structure you should probably split the component into smaller ones instead of adding comments.

5. State Management

• Pinia: Use Pinia for global state. It's the official recommendation over Vuex.

• Setup Stores: Prefer "Setup Stores" (function style) in Pinia for consistency with Composition API.

  export const useUserStore = defineStore('user', () => {
    const user = ref(null)
    const isLoggedIn = computed(() => !!user.value)
    function login() { /* ... */ }
    
    return { user, isLoggedIn, login }
  })
  

6. Performance

• v-memo: Use v-memo for optimization of large lists or complex sub-trees.
• v-once: Use for static content that never changes.
• Lazy Loading: Use defineAsyncComponent for route components or heavy distinct sections.
• Computed Stability: Ensure computed properties are side-effect free and stable.

7. Style Guide

• Scoped Styles: Always use <style scoped>.
• CSS Variables: Use CSS variables for theming to allow dynamic changes.
• BEM/Utility: Follow BEM or a utility interaction pattern (like Tailwind) consistent with the project.