0
# TypeScript Checker
1

2
TypeScript type checking integration using the built-in TypeScript compiler, providing real-time type checking in development and build-time validation.
3

4
## Capabilities
5

6
### TypeScript Configuration
7

8
Enable and configure TypeScript type checking with flexible options for development and build modes.
9

10
```typescript { .api }
11
/**
12
 * TypeScript checker configuration
13
 * - Set to `true` to enable type checking with default configuration
14
 * - Set to `false` to disable type checking
15
 * - Provide partial options object for custom configuration
16
 */
17
type TscConfig = 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
  typescript: true,
40
});
41

42
// Custom tsconfig path
43
checker({
44
  typescript: {
45
    tsconfigPath: './tsconfig.build.json',
46
  },
47
});
48

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

60
### Default Configuration
61

62
When `typescript: true` is used, the following default configuration is applied:
63

64
```typescript
65
{
66
  tsconfigPath: 'tsconfig.json',        // Look for tsconfig.json in project root
67
  typescriptPath: 'typescript',         // Use typescript from node_modules
68
  root: process.cwd(),                  // Use current working directory
69
  buildMode: false,                     // Enable incremental checking in dev mode
70
}
71
```
72

73
### Development Mode Behavior
74

75
In development mode, the TypeScript checker:
76

77
- Runs in a separate worker thread to avoid blocking the development server
78
- Performs incremental type checking for faster subsequent checks
79
- Reports type errors via the error overlay system
80
- Watches for file changes and re-runs type checking automatically
81
- Integrates with Vite's hot module replacement (HMR) system
82

83
### Build Mode Behavior
84

85
In build mode, the TypeScript checker:
86

87
- Runs the TypeScript compiler as a separate process
88
- Uses the configured `tsconfigPath` for type checking
89
- Exits the build process with non-zero exit code if type errors are found
90
- Can be disabled by setting `enableBuild: false` in shared configuration
91
- Supports `vite build --watch` mode without terminating the process
92

93
### Integration with TSConfig
94

95
The checker respects your TypeScript configuration:
96

97
```json
98
// tsconfig.json
99
{
100
  "compilerOptions": {
101
    "strict": true,
102
    "noUnusedLocals": true,
103
    "noUnusedParameters": true,
104
    // ... other TypeScript options
105
  },
106
  "include": ["src/**/*"],
107
  "exclude": ["node_modules", "dist"]
108
}
109
```
110

111
The checker will use these settings when performing type checking.
112

113
### Error Reporting
114

115
TypeScript errors are reported with detailed information:
116

117
- **File location**: Exact file path and line/column numbers
118
- **Error message**: TypeScript compiler error message
119
- **Code frame**: Highlighted code snippet showing the error context
120
- **Error code**: TypeScript error code (e.g., TS2322)
121

122
### Advanced Configuration
123

124
For complex projects, you can configure multiple aspects:
125

126
```typescript
127
checker({
128
  typescript: {
129
    // Use different tsconfig for development
130
    tsconfigPath: process.env.NODE_ENV === 'development' 
131
      ? './tsconfig.dev.json' 
132
      : './tsconfig.json',
133
    
134
    // Use specific TypeScript version
135
    typescriptPath: require.resolve('typescript/lib/typescript.js'),
136
    
137
    // Set root directory
138
    root: './packages/frontend',
139
    
140
    // Enable build mode optimizations
141
    buildMode: process.env.NODE_ENV === 'production',
142
  },
143
});
144
```
145

146
### Performance Tips
147

148
- Use `"incremental": true` in your tsconfig.json for faster subsequent type checks
149
- Consider using TypeScript project references for monorepo setups
150
- Exclude test files and node_modules in your tsconfig.json
151
- Use `"skipLibCheck": true` to skip type checking of declaration files if build performance is critical
152

153
### Troubleshooting
154

155
Common issues and solutions:
156

157
**TypeScript not found**: Ensure TypeScript is installed as a dependency
158
```bash
159
npm install --save-dev typescript
160
```
161

162
**Custom TypeScript version**: Specify the exact path to the TypeScript package
163
```typescript
164
typescript: {
165
  typescriptPath: require.resolve('typescript'),
166
}
167
```
168

169
**Different tsconfig for development**: Use separate configuration files
170
```typescript
171
typescript: {
172
  tsconfigPath: './tsconfig.dev.json',
173
}
174
```