Vue.js: TypeScript Best Practices

// ❌ Broken version: JS errors only surface at runtime
export default {
  props: {
    user: { type: Object, required: true }
    // Misspelled prop name: userName (no error)
    // Wrong prop type: no error
    // Misspelled emit event name: no error
  }
}

<!-- The parent passes userName, but the child declares user -->
<UserCard userName="Alice" />  <!-- ❌ Only discovered at runtime -->

<!-- Misspelled emit event name -->
<Child @updae="handler" />  <!-- ❌ Only discovered at runtime -->

<!-- Child component: UserCard.vue -->
<script setup lang="ts">
interface User {
  id: number
  name: string
  email: string
}

const props = defineProps<{
  user: User
  variant?: 'primary' | 'secondary'
}>()

const emit = defineEmits<{
  select: [userId: number]
  delete: [userId: number]
}>()
</script>

<!-- Used from the parent: errors at compile time -->
<UserCard :user="alice" />  <!-- ✅ Compile-time type checking -->
<UserCard @updae="handler" />  <!-- ❌ TS error: event does not exist -->

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "jsx": "preserve",
    "sourceMap": true,
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "skipLibCheck": true
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue"
  ]
}

{
  "compilerOptions": {
    // 1. Strict mode (always enable)
    "strict": true,
    
    // 2. No implicit any
    "noImplicitAny": true,
    
    // 3. Strict null checks
    "strictNullChecks": true,
    
    // 4. Strict function types
    "strictFunctionTypes": true,
    
    // 5. Strict bind / call / apply
    "strictBindCallApply": true
  }
}

src/
├── components/        # Shared components
│   ├── UserCard.vue   # <script setup lang="ts">
│   └── BaseButton.vue
├── views/             # Page components
├── stores/            # Pinia (TS)
├── composables/       # Composables
├── types/             # Type definitions
│   ├── user.ts        # export interface User
│   ├── api.ts         # export interface ApiResponse<T>
│   └── index.ts       # Re-exports
├── utils/             # Utility functions
├── router/            # Router (TS)
├── App.vue
└── main.ts            # Entry point

The tree is intended as a reference layout, not a rendered page.
Following it means component, view, store, composable, type, util, and router code each live in their own folder, types/index.ts re-exports User and ApiResponse<T> for a single import path, and main.ts (not main.js) is the entry point that creates the app.

src/components/UserCard.vue → imports { User } from '@/types'
src/stores/*.ts             → Pinia stores typed with interfaces
src/types/index.ts          → export * from './user'; export * from './api'
src/main.ts                 → createApp(App).use(router).use(pinia).mount('#app')

const props = defineProps<{
  name: string
  age: number
  active: boolean
}>()

// withDefaults supplies the defaults
const props = withDefaults(defineProps<{
  name: string
  age?: number
  variant?: 'primary' | 'secondary'
}>(), {
  age: 18,
  variant: 'primary'
})

interface User {
  id: number
  name: string
  email: string
}

const props = defineProps<{
  user: User
  items: User[]
  config: Record<string, unknown>
}>()

const props = defineProps<{
  formatter: (value: number) => string
  onChange: (value: string) => void
}>()

// Generic component: List<T> lets you specify the item type
<script setup lang="ts" generic="T extends { id: number }">
defineProps<{
  items: T[]
  selected?: T
}>()
</script>

<!-- Usage -->
<List :items="users" />  <!-- T = User -->
<List :items="products" />  <!-- T = Product -->

// 1. Simple events
const emit = defineEmits<{
  click: []
  submit: []
}>()

// 2. Single parameter
const emit = defineEmits<{
  select: [id: number]
  delete: [id: number]
}>()

// 3. Multiple parameters
const emit = defineEmits<{
  change: [id: number, oldValue: string, newValue: string]
}>()

// 4. Optional parameters
const emit = defineEmits<{
  search: [query?: string]
  load: [id: number, options?: object]
}>()

// 5. void return value
const emit = defineEmits<{
  success: [data: object]
  error: [message: string]
}>()

const emit = defineEmits<{
  select: [id: number]
  delete: [id: number]
}>()

// ✅ TypeScript checks the argument types
emit('select', 123)  // ✅ OK
emit('select', 'abc')  // ❌ TS error
emit('delete', 456)

const { ref } = Vue

// Inferred as Ref<number>
const count = ref(0)
count.value = 1  // ✅

// Inferred as Ref<string>
const name = ref('Alice')

// Inferred as Ref<number | undefined> (may be undefined)
const maybeNumber = ref<number>()
maybeNumber.value  // type: number | undefined

const { reactive } = Vue

// Inferred automatically
const state = reactive({
  count: 0,
  user: { name: 'Alice', age: 25 }
})

state.count  // type: number
state.user.name  // type: string

// Explicit type
interface State {
  count: number
  items: string[]
}
const s = reactive<State>({
  count: 0,
  items: []
})

const { ref, computed } = Vue

const count = ref(10)

// Inferred automatically: ComputedRef<number>
const double = computed(() => count.value * 2)

// Explicit type
const formatted = computed<string>(() => `Count: ${count.value}`)

A single line of text plus a button.
The line starts as count: 0 and renders the empty-state placeholder for user because the value is null;
each click on +1 re-renders the same line with the counter incremented, while user stays null and keeps showing that placeholder.

Before click:  count: 0 | user: (empty)
After click:   count: 1 | user: (empty)
After 3 more:  count: 4 | user: (empty)

<template>
  <input ref="usernameInput">
  <MyChart ref="chartComponent" :data="chartData" />
</template>

<script setup lang="ts">
const { useTemplateRef, onMounted } = Vue
import MyChart from './MyChart.vue'

// ✅ TS infers: Ref<HTMLInputElement | null>
const inputRef = useTemplateRef<HTMLInputElement>('usernameInput')

// ✅ Component instance type
const chartRef = useTemplateRef<InstanceType<typeof MyChart>>('chartComponent')

onMounted(() => {
  inputRef.value?.focus()  // TS autocompletion
  chartRef.value?.refresh()
})
</script>

// Old way: you must write the ref<> type yourself
const { ref, onMounted } = Vue
import MyChart from './MyChart.vue'

const inputRef = ref<HTMLInputElement | null>(null)
const chartRef = ref<InstanceType<typeof MyChart> | null>(null)

# Install the "Vue - Official" extension (Volar) in VS Code
# Search for: Vue - Official

{
  "vue.enabled.volar": true,
  "vue.compilerOptions.target": 3.4,
  "vue.complete.casing.tags": ["PascalCase", "snake_case"],
  
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.preferences.includePackageJsonAutoImports": "on",
  
  "editor.formatOnSave": true,
  "[vue]": {
    "editor.defaultFormatter": "Vue.volar"
  }
}

// ✅ 5 defineProps patterns
// 1. Basic
defineProps<{ name: string }>()

// 2. Optional + default
withDefaults(defineProps<{ name?: string }>(), { name: 'Guest' })

// 3. Complex
defineProps<{ user: User; items: User[] }>()

// 4. Function
defineProps<{ onClick: () => void }>()

// 5. Generic (requires generic="T")
defineProps<{ items: T[] }>()

// ✅ 5 defineEmits event shapes
// 1. Simple
defineEmits<{ click: [] }>()

// 2. Single argument
defineEmits<{ select: [id: number] }>()

// 3. Multiple arguments
defineEmits<{ change: [old: string, new: string] }>()

// 4. Optional
defineEmits<{ search: [q?: string] }>()

// 5. void
defineEmits<{ done: [] }>()

// ✅ ref<T> + type inference
import { ref } from 'vue'
const count = ref(0)             // inferred as Ref<number>
const user = ref<User | null>(null)

These snippets are documentation of macro signatures and are not rendered on their own.
In a Vite + TS project, Volar reports a type error for any call that violates the declarations — for example emit('select', 'abc') or a prop passed with the wrong shape — and shows the inferred type (Ref<number>, Ref<User | null>) on hover.

Volar hover / diagnostics:
count        → Ref<number>
user         → Ref<User | null>
defineProps<{ name?: string }>() + withDefaults → name: string (default 'Guest')
emit('select', 'abc') → ❌ Argument of type 'string' is not assignable to 'number'