0
# Vue TSC
1

2
Vue TSC is a command-line TypeScript compiler specifically designed for Vue 3 applications. It extends the standard TypeScript compiler to understand Vue Single File Components (.vue files), enabling type checking and declaration file generation for Vue projects with full type safety.
3

4
## Package Information
5

6
- **Package Name**: vue-tsc
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vue-tsc typescript`
10

11
## Core Imports
12

13
```typescript
14
import { run } from "vue-tsc";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { run } = require("vue-tsc");
21
```
22

23
## Basic Usage
24

25
**CLI Usage (most common):**
26

27
```bash
28
# Type checking only (recommended for CI/CD)
29
vue-tsc --noEmit
30

31
# Generate declaration files for Vue components
32
vue-tsc --declaration --emitDeclarationOnly
33

34
# Use with TypeScript build mode
35
vue-tsc --build
36

37
# Pass any TypeScript compiler options
38
vue-tsc --strict --target ES2020
39
```
40

41
**Programmatic Usage:**
42

43
```typescript
44
import { run } from "vue-tsc";
45

46
// Use default TypeScript compiler
47
run();
48

49
// Use custom TypeScript compiler path
50
run("/path/to/custom/typescript/lib/tsc");
51
```
52

53
## Architecture
54

55
Vue TSC integrates several key components to provide Vue-aware TypeScript compilation:
56

57
- **TypeScript Compiler Integration**: Wraps the standard TypeScript compiler (`tsc`) with Vue language support
58
- **Vue Language Plugin**: Uses `@vue/language-core` to parse and understand Vue Single File Components
59
- **Volar Integration**: Leverages `@volar/typescript` for high-performance TypeScript language services
60
- **Extension Management**: Dynamically handles file extensions based on Vue project configuration
61
- **CLI Wrapper**: Provides a command-line interface that passes through TypeScript compiler options
62

63
## Capabilities
64

65
### Programmatic API
66

67
Core function for integrating Vue TypeScript compilation into custom build tools or processes.
68

69
```typescript { .api }
70
/**
71
 * Executes TypeScript compilation with Vue Single File Component support
72
 * @param tscPath - Optional path to TypeScript compiler executable
73
 * @returns Result from the underlying TypeScript compilation process
74
 */
75
function run(tscPath?: string): any;
76
```
77

78
The `run` function:
79
- **Default Behavior**: Uses `require.resolve('typescript/lib/tsc')` when no path provided
80
- **Vue Integration**: Automatically configures Vue language plugin for `.vue` file support
81
- **Extension Handling**: Dynamically adapts to project-specific file extensions
82
- **Error Recovery**: Implements retry logic for configuration changes during compilation
83
- **TypeScript Passthrough**: Forwards compilation to underlying TypeScript compiler with Vue enhancements
84

85
### CLI Interface
86

87
Command-line tool that provides Vue-aware TypeScript compilation for development workflows.
88

89
```bash { .api }
90
# Primary CLI command
91
vue-tsc [typescript-options]
92

93
# Common usage patterns:
94
vue-tsc --noEmit                    # Type checking only
95
vue-tsc --declaration --emitDeclarationOnly  # Generate .d.ts files
96
```
97

98
**CLI Features:**
99
- **TypeScript Option Support**: Accepts all standard TypeScript compiler flags and options
100
- **Project Configuration**: Reads from `tsconfig.json` with Vue-specific extensions
101
- **Build Mode**: Supports `--build` flag for TypeScript project references
102
- **Output Control**: Compatible with `--noEmit`, `--declaration`, and other output options
103
- **Integration Ready**: Designed for use in npm scripts, CI/CD pipelines, and build processes
104

105
## Types
106

107
```typescript { .api }
108
// Return type from run() function - matches TypeScript compiler output
109
type CompilationResult = any;
110

111
// Internal Vue configuration options (from @vue/language-core)
112
interface VueCompilerOptions {
113
  extensions: string[];
114
  // Additional Vue-specific compiler options
115
}
116

117
// Vue language plugin configuration
118
interface VueLanguagePlugin {
119
  // Plugin interface for TypeScript language service integration
120
}
121
```
122

123
## Dependencies
124

125
Vue TSC requires these peer and runtime dependencies:
126

127
- **TypeScript**: `>=5.0.0` (peer dependency)
128
- **@volar/typescript**: `2.4.23` (TypeScript language service integration)
129
- **@vue/language-core**: `3.0.6` (Vue language support and SFC parsing)
130

131
## Error Handling
132

133
The tool handles several error scenarios:
134

135
- **Extension Changes**: Automatically retries compilation if Vue file extensions change during processing
136
- **Configuration Errors**: Passes through TypeScript configuration errors with Vue context
137
- **Missing Dependencies**: Requires TypeScript as a peer dependency with clear error messages
138
- **File Processing**: Handles `.vue` file parsing errors through the Vue language core
139

140
## Common Use Cases
141

142
**Development Workflow:**
143
```bash
144
# Add to package.json scripts
145
{
146
  "scripts": {
147
    "type-check": "vue-tsc --noEmit",
148
    "build-types": "vue-tsc --declaration --emitDeclarationOnly"
149
  }
150
}
151
```
152

153
**CI/CD Pipeline:**
154
```bash
155
# Type checking in continuous integration
156
npm run type-check
157
```
158

159
**Library Development:**
160
```bash
161
# Generate declaration files for Vue component libraries
162
vue-tsc --declaration --emitDeclarationOnly --outDir dist/types
163
```