0
# Vue TypeScript Checker
1

2
Vue Single File Component type checking using vue-tsc, providing comprehensive TypeScript integration for Vue.js projects with full SFC support.
3

4
## Capabilities
5

6
### Vue TypeScript Configuration
7

8
Enable and configure Vue TypeScript checking with the same flexible options as the regular TypeScript checker, specifically optimized for Vue SFC files.
9

10
```typescript { .api }
11
/**
12
 * Vue TypeScript checker configuration
13
 * - Set to `true` to enable vue-tsc checking with default configuration
14
 * - Set to `false` to disable vue-tsc checking
15
 * - Provide partial options object for custom configuration
16
 */
17
type VueTscConfig = boolean | Partial<TsConfigOptions>;
18

19
interface TsConfigOptions {
20
  /** Path to tsconfig.json file */
21
  tsconfigPath: string;
22
  
23
  /** Path to typescript package */
24
  typescriptPath: string;
25
  
26
  /** Root path of current working directory */
27
  root: string;
28
  
29
  /** Enable build mode flag */
30
  buildMode: boolean;
31
}
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
// Simple enable with defaults
38
checker({
39
  vueTsc: true,
40
});
41

42
// Custom tsconfig for Vue
43
checker({
44
  vueTsc: {
45
    tsconfigPath: './tsconfig.vue.json',
46
  },
47
});
48

49
// Full custom configuration
50
checker({
51
  vueTsc: {
52
    tsconfigPath: './tsconfig.json',
53
    typescriptPath: require.resolve('typescript'),
54
    root: './src',
55
    buildMode: false,
56
  },
57
});
58
```
59

60
### Vue-Specific TypeScript Configuration
61

62
For optimal Vue TypeScript checking, your tsconfig.json should include Vue-specific settings:
63

64
```json
65
{
66
  "compilerOptions": {
67
    "target": "ES2020",
68
    "module": "ESNext",
69
    "moduleResolution": "bundler",
70
    "jsx": "preserve",
71
    "strict": true,
72
    "skipLibCheck": true,
73
    "isolatedModules": true,
74
    "types": ["vite/client"]
75
  },
76
  "include": [
77
    "src/**/*.ts",
78
    "src/**/*.tsx", 
79
    "src/**/*.vue"
80
  ],
81
  "exclude": ["node_modules"]
82
}
83
```
84

85
### Single File Component Support
86

87
The Vue TypeScript checker provides comprehensive support for Vue Single File Components:
88

89
**Template Type Checking:**
90
- Expression type validation in templates
91
- Prop type checking in template usage
92
- Event handler type validation
93
- Directive argument and modifier validation
94

95
**Script Setup Support:**
96
- Full TypeScript support in `<script setup>` blocks
97
- Automatic type inference for refs and reactive variables
98
- Props and emit type checking
99
- Composable function type validation
100

101
**Composition API Integration:**
102
- Type-safe reactive references
103
- Computed property type inference  
104
- Watch callback type checking
105
- Lifecycle hook parameter validation
106

107
### Default Configuration
108

109
When `vueTsc: true` is used, the following default configuration is applied:
110

111
```typescript
112
{
113
  tsconfigPath: 'tsconfig.json',        // Look for tsconfig.json in project root
114
  typescriptPath: 'typescript',         // Use typescript from node_modules  
115
  root: process.cwd(),                  // Use current working directory
116
  buildMode: false,                     // Enable incremental checking in dev mode
117
}
118
```
119

120
### Development Mode Behavior
121

122
In development mode, the Vue TypeScript checker:
123

124
- Runs vue-tsc in a separate worker thread for non-blocking type checking
125
- Performs incremental type checking of Vue SFCs and TypeScript files
126
- Reports template and script errors via the error overlay system
127
- Watches for changes in .vue, .ts, and .tsx files
128
- Integrates with Vite's HMR system for immediate feedback
129
- Validates prop types, emit declarations, and template expressions
130

131
### Build Mode Behavior
132

133
In build mode, the Vue TypeScript checker:
134

135
- Runs vue-tsc as a separate process for comprehensive type checking
136
- Validates entire Vue project including all SFC files
137
- Reports both TypeScript and Vue template type errors
138
- Exits build process with error code if type issues are found
139
- Supports `vite build --watch` mode for continuous validation
140

141
### Vue SFC Type Checking Features
142

143
**Props Validation:**
144
```vue
145
<script setup lang="ts">
146
interface Props {
147
  message: string;
148
  count?: number;
149
}
150

151
const props = withDefaults(defineProps<Props>(), {
152
  count: 0
153
});
154
</script>
155

156
<template>
157
  <!-- Type-checked template usage -->
158
  <div>{{ props.message }} - {{ props.count }}</div>
159
</template>
160
```
161

162
**Emit Type Checking:**
163
```vue
164
<script setup lang="ts">
165
interface Emits {
166
  update: [value: string];
167
  change: [id: number, data: object];
168
}
169

170
const emit = defineEmits<Emits>();
171

172
// Type-checked emit calls
173
emit('update', 'new value');
174
emit('change', 1, { data: true });
175
</script>
176
```
177

178
**Ref and Reactive Type Inference:**
179
```vue
180
<script setup lang="ts">
181
import { ref, reactive } from 'vue';
182

183
const count = ref(0);           // Ref<number>
184
const message = ref('hello');   // Ref<string>
185

186
const state = reactive({        // Reactive<{ items: Item[] }>
187
  items: [] as Item[]
188
});
189
</script>
190
```
191

192
### Error Reporting
193

194
Vue TypeScript errors are reported with detailed Vue-specific information:
195

196
- **SFC section**: Template, script, or style block location
197
- **Vue feature**: Props, emit, computed, or template expression context
198
- **Type information**: Expected vs actual types in Vue context
199
- **Template location**: Exact line/column in template blocks
200
- **Code frame**: Highlighted Vue SFC code snippet
201

202
### Integration with Vue Tools
203

204
The checker works alongside other Vue development tools:
205

206
**With Vetur/Volar:**
207
```typescript
208
checker({
209
  // Use vue-tsc for type checking
210
  vueTsc: true,
211
  // Vetur/Volar provides editor integration
212
});
213
```
214

215
**With Vue Router:**
216
```typescript
217
// Ensure router types are included
218
vueTsc: {
219
  tsconfigPath: './tsconfig.json', // Should include vue-router types
220
}
221
```
222

223
**With Pinia:**
224
```typescript
225
// Type-safe store integration
226
vueTsc: {
227
  tsconfigPath: './tsconfig.json', // Should include pinia types  
228
}
229
```
230

231
### Performance Optimization
232

233
For large Vue projects, consider these optimizations:
234

235
```json
236
// tsconfig.json
237
{
238
  "compilerOptions": {
239
    "incremental": true,           // Enable incremental compilation
240
    "skipLibCheck": true,          // Skip lib type checking
241
    "isolatedModules": true        // Enable faster builds
242
  },
243
  "vueCompilerOptions": {
244
    "target": 3.3                  // Target Vue 3.3+ for better performance
245
  }
246
}
247
```
248

249
### Troubleshooting
250

251
**Vue-tsc not found:**
252
```bash
253
npm install --save-dev vue-tsc typescript
254
```
255

256
**Template type errors:**
257
Ensure your tsconfig includes Vue files:
258
```json
259
{
260
  "include": ["src/**/*.vue", "src/**/*.ts"]
261
}
262
```
263

264
**Script setup issues:**
265
Verify Vue version compatibility:
266
```bash
267
npm install vue@^3.3.0 vue-tsc@^3.0.0
268
```
269

270
**Performance issues with large projects:**
271
```typescript
272
vueTsc: {
273
  tsconfigPath: './tsconfig.vue.json', // Separate config for Vue files only
274
  buildMode: true,                     // Enable build optimizations
275
}
276
```