0
# TypeScript Integration
1

2
TypeScript compiler integration with language service, diagnostics, and type checking capabilities.
3

4
## Capabilities
5

6
### TypeScript Service Management
7

8
The plugin creates and manages a TypeScript Language Service for compilation and type checking.
9

10
```typescript { .api }
11
/**
12
 * TypeScript module interface (can be customized via options.typescript)
13
 */
14
interface TypeScriptModule {
15
  /** TypeScript version string */
16
  version: string;
17
  
18
  /** Create a language service instance */
19
  createLanguageService(host: LanguageServiceHost, documentRegistry?: DocumentRegistry): LanguageService;
20
  
21
  /** Create a document registry for caching */
22
  createDocumentRegistry(): DocumentRegistry;
23
  
24
  /** Resolve module names using Node.js resolution */
25
  nodeModuleNameResolver(moduleName: string, containingFile: string, options: CompilerOptions, host: ModuleResolutionHost): ResolvedModuleWithFailedLookupLocations;
26
  
27
  /** System interface for file operations */
28
  sys: System;
29
}
30
```
31

32
### Language Service Host
33

34
Custom language service host implementation for Rollup integration.
35

36
```typescript { .api }
37
/**
38
 * Language service host that bridges Rollup and TypeScript
39
 */
40
class LanguageServiceHost implements tsTypes.LanguageServiceHost {
41
  /** Set source code snapshot for a file */
42
  setSnapshot(id: string, code: string): tsTypes.IScriptSnapshot;
43
  
44
  /** Get script snapshot for a file */
45
  getScriptSnapshot(fileName: string): tsTypes.IScriptSnapshot | undefined;
46
  
47
  /** Get TypeScript compilation options */
48
  getCompilationSettings(): tsTypes.CompilerOptions;
49
  
50
  /** Get list of script file names */
51
  getScriptFileNames(): string[];
52
  
53
  /** Get script version for caching */
54
  getScriptVersion(fileName: string): string;
55
  
56
  /** Set language service reference */
57
  setLanguageService(service: tsTypes.LanguageService): void;
58
}
59
```
60

61
### Configuration Parsing
62

63
TSConfig file parsing and option merging functionality.
64

65
```typescript { .api }
66
/**
67
 * Parse and merge TypeScript configuration
68
 * @param context - Rollup context for logging
69
 * @param pluginOptions - Plugin configuration options
70
 * @returns Parsed configuration and file name
71
 */
72
function parseTsConfig(
73
  context: RollupContext, 
74
  pluginOptions: IOptions
75
): {
76
  parsedTsConfig: tsTypes.ParsedCommandLine;
77
  fileName: string | undefined;
78
};
79

80
/**
81
 * Parsed TypeScript configuration result
82
 */
83
interface ParsedCommandLine {
84
  /** Compiler options after all merging */
85
  options: tsTypes.CompilerOptions;
86
  
87
  /** List of files to include in compilation */
88
  fileNames: string[];
89
  
90
  /** Type reference directives */
91
  typeReferenceDirectives: tsTypes.FileReference[];
92
  
93
  /** Configuration errors */
94
  errors: tsTypes.Diagnostic[];
95
}
96
```
97

98
### Diagnostic Processing
99

100
TypeScript diagnostic message collection and formatting.
101

102
```typescript { .api }
103
/**
104
 * Convert TypeScript diagnostics to plugin format
105
 * @param type - Diagnostic type identifier
106
 * @param diagnostics - Array of TypeScript diagnostics
107
 * @returns Converted diagnostic objects
108
 */
109
function convertDiagnostic(
110
  type: string, 
111
  diagnostics: readonly tsTypes.Diagnostic[]
112
): PluginDiagnostic[];
113

114
/**
115
 * Print diagnostics to console with formatting
116
 * @param context - Rollup context for output
117
 * @param diagnostics - Diagnostics to display
118
 * @param pretty - Enable pretty printing
119
 */
120
function printDiagnostics(
121
  context: RollupContext, 
122
  diagnostics: PluginDiagnostic[], 
123
  pretty: boolean
124
): void;
125

126
interface PluginDiagnostic {
127
  /** Source file name */
128
  fileName?: string;
129
  
130
  /** Line number (1-based) */
131
  line?: number;
132
  
133
  /** Column number (1-based) */
134
  column?: number;
135
  
136
  /** Diagnostic message text */
137
  messageText: string;
138
  
139
  /** TypeScript diagnostic category */
140
  category: tsTypes.DiagnosticCategory;
141
  
142
  /** Diagnostic code number */
143
  code: number;
144
}
145
```
146

147
### Compilation and Emit
148

149
TypeScript compilation and JavaScript/declaration file generation.
150

151
```typescript { .api }
152
/**
153
 * Emit output from TypeScript compiler
154
 */
155
interface EmitOutput {
156
  /** Files generated by compilation */
157
  outputFiles: OutputFile[];
158
  
159
  /** Whether emit was skipped due to errors */
160
  emitSkipped: boolean;
161
}
162

163
interface OutputFile {
164
  /** Output file name */
165
  name: string;
166
  
167
  /** File content text */
168
  text: string;
169
  
170
  /** Whether to write byte order mark */
171
  writeByteOrderMark: boolean;
172
}
173

174
/**
175
 * Convert emit output to plugin format
176
 * @param output - TypeScript emit output
177
 * @param references - File references for dependency tracking
178
 * @returns Converted code result
179
 */
180
function convertEmitOutput(
181
  output: tsTypes.EmitOutput, 
182
  references?: string[]
183
): ICode;
184

185
interface ICode {
186
  /** Generated JavaScript code */
187
  code: string;
188
  
189
  /** Source map content */
190
  map?: string;
191
  
192
  /** Declaration file content */
193
  dts?: tsTypes.OutputFile;
194
  
195
  /** Declaration map content */
196
  dtsmap?: tsTypes.OutputFile;
197
  
198
  /** Referenced files for dependency tracking */
199
  references?: string[];
200
}
201
```
202

203
**Usage Examples:**
204

205
```javascript
206
// Custom TypeScript version
207
import ttypescript from 'ttypescript';
208

209
typescript({
210
  typescript: ttypescript,  // Use ttypescript instead of typescript
211
  transformers: [
212
    // Custom transformers work with alternative TS implementations
213
    (service) => ({
214
      before: [myCustomTransformer(service.getProgram())]
215
    })
216
  ]
217
})
218

219
// Version checking and compatibility
220
typescript({
221
  // Plugin automatically validates TypeScript version
222
  // Supported range: TypeScript 2.4+
223
  // Rollup 1.26.3+
224
  
225
  verbosity: 2  // Will log version information
226
})
227
```
228

229
### Error Handling and Recovery
230

231
Comprehensive error handling for compilation failures and diagnostic reporting.
232

233
```typescript { .api }
234
/**
235
 * Error recovery strategies
236
 */
237
interface ErrorHandling {
238
  /** Continue compilation despite syntax errors */
239
  abortOnError: boolean;
240
  
241
  /** Skip emit for files with errors */
242
  emitSkipped: boolean;
243
  
244
  /** Collect diagnostics without stopping build */
245
  diagnosticCollection: PluginDiagnostic[];
246
}
247
```
248

249
**Error Handling Examples:**
250

251
```javascript
252
// Strict error handling (default)
253
typescript({
254
  abortOnError: true,    // Stop on first error
255
  check: true           // Enable type checking
256
})
257

258
// Lenient error handling
259
typescript({
260
  abortOnError: false,   // Continue despite errors
261
  check: true,          // Still collect diagnostics
262
  verbosity: 1          // Show warnings and errors
263
})
264

265
// Transpile-only mode (fastest)
266
typescript({
267
  check: false,         // Skip all type checking
268
  verbosity: 0         // Only show critical errors
269
})
270
```
271

272
### Module Resolution
273

274
Integration with TypeScript's module resolution system for proper import handling.
275

276
```typescript { .api }
277
/**
278
 * Module resolution integration
279
 */
280
interface ModuleResolution {
281
  /** Resolve import statements */
282
  nodeModuleNameResolver(
283
    importee: string, 
284
    importer: string, 
285
    options: tsTypes.CompilerOptions,
286
    host: tsTypes.ModuleResolutionHost
287
  ): tsTypes.ResolvedModuleWithFailedLookupLocations;
288
  
289
  /** Supported module resolution strategies */
290
  strategies: 'node10' | 'node16' | 'nodenext' | 'bundler';
291
}
292
```
293

294
The plugin automatically handles:
295
- TypeScript file extensions (`.ts`, `.tsx`, `.cts`, `.mts`)
296
- Declaration file exclusion (`.d.ts` files)
297
- Import resolution through TypeScript's resolver
298
- Type-only import handling for watch mode compatibility