0
# Transpilation
1

2
Simple and fast TypeScript-to-JavaScript conversion without full type checking. Ideal for build tools and development servers that need quick compilation.
3

4
## Capabilities
5

6
### Module Transpilation
7

8
Transpile a single TypeScript module to JavaScript.
9

10
```typescript { .api }
11
/**
12
 * Transpile a TypeScript module to JavaScript
13
 * @param input - TypeScript source code
14
 * @param transpileOptions - Transpilation options
15
 * @returns Transpiled JavaScript output with diagnostics
16
 */
17
function transpileModule(input: string, transpileOptions: TranspileOptions): TranspileOutput;
18

19
interface TranspileOptions {
20
  compilerOptions?: CompilerOptions;
21
  fileName?: string;
22
  reportDiagnostics?: boolean;
23
  moduleName?: string;
24
  renamedDependencies?: MapLike<string>;
25
  transformers?: CustomTransformers;
26
}
27

28
interface TranspileOutput {
29
  outputText: string;
30
  diagnostics?: Diagnostic[];
31
  sourceMapText?: string;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import * as ts from "typescript";
39

40
// Basic transpilation
41
const result = ts.transpileModule(`
42
  interface User {
43
    name: string;
44
    age: number;
45
  }
46
  
47
  const user: User = { name: "Alice", age: 30 };
48
  const greeting = \`Hello, \${user.name}!\`;
49
  console.log(greeting);
50
`, {
51
  compilerOptions: {
52
    module: ts.ModuleKind.CommonJS,
53
    target: ts.ScriptTarget.ES5,
54
    sourceMap: true
55
  }
56
});
57

58
console.log("JavaScript output:");
59
console.log(result.outputText);
60
console.log("Source map:");
61
console.log(result.sourceMapText);
62

63
// Transpile with JSX
64
const jsxResult = ts.transpileModule(`
65
  import React from 'react';
66
  
67
  interface Props {
68
    name: string;
69
  }
70
  
71
  const Greeting: React.FC<Props> = ({ name }) => {
72
    return <div>Hello, {name}!</div>;
73
  };
74
  
75
  export default Greeting;
76
`, {
77
  compilerOptions: {
78
    module: ts.ModuleKind.ESNext,
79
    target: ts.ScriptTarget.ES2018,
80
    jsx: ts.JsxEmit.React,
81
    esModuleInterop: true
82
  },
83
  fileName: "Greeting.tsx"
84
});
85

86
console.log(jsxResult.outputText);
87
```
88

89
### Simple Transpilation
90

91
Transpile TypeScript code with minimal configuration.
92

93
```typescript { .api }
94
/**
95
 * Simple TypeScript to JavaScript transpilation
96
 * @param input - TypeScript source code
97
 * @param compilerOptions - Optional compiler options
98
 * @param fileName - Optional file name for diagnostics
99
 * @param diagnostics - Optional array to receive diagnostics
100
 * @param moduleName - Optional module name
101
 * @returns JavaScript output text
102
 */
103
function transpile(
104
  input: string,
105
  compilerOptions?: CompilerOptions,
106
  fileName?: string,
107
  diagnostics?: Diagnostic[],
108
  moduleName?: string
109
): string;
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
import * as ts from "typescript";
116

117
// Simple transpilation with minimal options
118
const jsCode = ts.transpile(`
119
  enum Color {
120
    Red = "red",
121
    Green = "green",
122
    Blue = "blue"
123
  }
124
  
125
  function paintHouse(color: Color): string {
126
    return \`The house is painted \${color}\`;
127
  }
128
  
129
  console.log(paintHouse(Color.Blue));
130
`, {
131
  target: ts.ScriptTarget.ES2015,
132
  module: ts.ModuleKind.CommonJS
133
});
134

135
console.log(jsCode);
136

137
// With diagnostics collection
138
const diagnostics: ts.Diagnostic[] = [];
139
const result = ts.transpile(`
140
  let message: string = 42; // Type error
141
  console.log(message);
142
`, {
143
  target: ts.ScriptTarget.ES2018
144
}, "example.ts", diagnostics);
145

146
if (diagnostics.length > 0) {
147
  console.log("Transpilation diagnostics:");
148
  diagnostics.forEach(diag => {
149
    console.log(ts.flattenDiagnosticMessageText(diag.messageText, '\n'));
150
  });
151
}
152
```
153

154
### Transpilation with Custom Transformers
155

156
Apply custom AST transformations during transpilation.
157

158
```typescript { .api }
159
interface TranspileOptions {
160
  compilerOptions?: CompilerOptions;
161
  fileName?: string;
162
  reportDiagnostics?: boolean;
163
  moduleName?: string;
164
  renamedDependencies?: MapLike<string>;
165
  transformers?: CustomTransformers;
166
}
167

168
interface CustomTransformers {
169
  before?: readonly TransformerFactory<SourceFile>[];
170
  after?: readonly TransformerFactory<SourceFile>[];
171
  afterDeclarations?: readonly TransformerFactory<Bundle | SourceFile>[];
172
}
173

174
type TransformerFactory<T extends Node> = (context: TransformationContext) => Transformer<T>;
175
type Transformer<T extends Node> = (node: T) => T;
176
```
177

178
**Usage Examples:**
179

180
```typescript
181
import * as ts from "typescript";
182

183
// Custom transformer that adds console.log to function entries
184
const addLoggingTransformer: ts.TransformerFactory<ts.SourceFile> = (context) => {
185
  return (sourceFile) => {
186
    function visitor(node: ts.Node): ts.Node {
187
      if (ts.isFunctionDeclaration(node) && node.name) {
188
        const logStatement = ts.factory.createExpressionStatement(
189
          ts.factory.createCallExpression(
190
            ts.factory.createPropertyAccessExpression(
191
              ts.factory.createIdentifier("console"),
192
              ts.factory.createIdentifier("log")
193
            ),
194
            undefined,
195
            [ts.factory.createStringLiteral(`Entering function: ${node.name.text}`)]
196
          )
197
        );
198
        
199
        const newBody = ts.factory.updateBlock(
200
          node.body!,
201
          [logStatement, ...node.body!.statements]
202
        );
203
        
204
        return ts.factory.updateFunctionDeclaration(
205
          node,
206
          node.modifiers,
207
          node.asteriskToken,
208
          node.name,
209
          node.typeParameters,
210
          node.parameters,
211
          node.type,
212
          newBody
213
        );
214
      }
215
      return ts.visitEachChild(node, visitor, context);
216
    }
217
    return ts.visitNode(sourceFile, visitor);
218
  };
219
};
220

221
// Use custom transformer
222
const result = ts.transpileModule(`
223
  function greet(name: string): string {
224
    return \`Hello, \${name}!\`;
225
  }
226
  
227
  function calculate(a: number, b: number): number {
228
    return a + b;
229
  }
230
`, {
231
  compilerOptions: {
232
    target: ts.ScriptTarget.ES2015,
233
    module: ts.ModuleKind.CommonJS
234
  },
235
  transformers: {
236
    before: [addLoggingTransformer]
237
  }
238
});
239

240
console.log(result.outputText);
241
```
242

243
### JSX Transpilation
244

245
Transpile JSX and TSX files to JavaScript.
246

247
```typescript { .api }
248
enum JsxEmit {
249
  None = 0,
250
  Preserve = 1,
251
  React = 2,
252
  ReactNative = 3,
253
  ReactJSX = 4,
254
  ReactJSXDev = 5
255
}
256
```
257

258
**Usage Examples:**
259

260
```typescript
261
import * as ts from "typescript";
262

263
// React JSX transpilation
264
const reactResult = ts.transpileModule(`
265
  import React from 'react';
266
  
267
  interface ButtonProps {
268
    label: string;
269
    onClick: () => void;
270
    disabled?: boolean;
271
  }
272
  
273
  const Button: React.FC<ButtonProps> = ({ label, onClick, disabled = false }) => {
274
    return (
275
      <button 
276
        onClick={onClick} 
277
        disabled={disabled}
278
        className="btn"
279
      >
280
        {label}
281
      </button>
282
    );
283
  };
284
  
285
  export default Button;
286
`, {
287
  compilerOptions: {
288
    target: ts.ScriptTarget.ES2018,
289
    module: ts.ModuleKind.ESNext,
290
    jsx: ts.JsxEmit.React,
291
    jsxFactory: "React.createElement",
292
    esModuleInterop: true
293
  },
294
  fileName: "Button.tsx"
295
});
296

297
// Modern React JSX transform
298
const modernReactResult = ts.transpileModule(`
299
  interface CardProps {
300
    title: string;
301
    children: React.ReactNode;
302
  }
303
  
304
  export const Card: React.FC<CardProps> = ({ title, children }) => {
305
    return (
306
      <div className="card">
307
        <h2>{title}</h2>
308
        <div className="card-content">
309
          {children}
310
        </div>
311
      </div>
312
    );
313
  };
314
`, {
315
  compilerOptions: {
316
    target: ts.ScriptTarget.ES2020,
317
    module: ts.ModuleKind.ESNext,
318
    jsx: ts.JsxEmit.ReactJSX, // Modern transform
319
    moduleResolution: ts.ModuleResolutionKind.NodeJs
320
  },
321
  fileName: "Card.tsx"
322
});
323

324
console.log("Classic React transform:");
325
console.log(reactResult.outputText);
326
console.log("\nModern React transform:");
327
console.log(modernReactResult.outputText);
328
```
329

330
### Configuration for Transpilation
331

332
Common compiler options for transpilation scenarios.
333

334
```typescript { .api }
335
interface CompilerOptions {
336
  // Essential for transpilation
337
  target?: ScriptTarget;
338
  module?: ModuleKind;
339
  jsx?: JsxEmit;
340
  
341
  // Output control
342
  sourceMap?: boolean;
343
  inlineSourceMap?: boolean;
344
  removeComments?: boolean;
345
  downlevelIteration?: boolean;
346
  
347
  // Module resolution
348
  esModuleInterop?: boolean;
349
  allowSyntheticDefaultImports?: boolean;
350
  moduleResolution?: ModuleResolutionKind;
351
  
352
  // Type checking (usually disabled for fast transpilation)
353
  skipLibCheck?: boolean;
354
  noEmit?: boolean;
355
  isolatedModules?: boolean;
356
  
357
  // JSX-specific
358
  jsxFactory?: string;
359
  jsxFragmentFactory?: string;
360
  jsxImportSource?: string;
361
}
362
```
363

364
**Common Configurations:**
365

366
```typescript
367
// Node.js target (CommonJS)
368
const nodeConfig: ts.CompilerOptions = {
369
  target: ts.ScriptTarget.ES2020,
370
  module: ts.ModuleKind.CommonJS,
371
  esModuleInterop: true,
372
  skipLibCheck: true,
373
  isolatedModules: true
374
};
375

376
// Modern browser target (ES modules)
377
const browserConfig: ts.CompilerOptions = {
378
  target: ts.ScriptTarget.ES2020,
379
  module: ts.ModuleKind.ESNext,
380
  moduleResolution: ts.ModuleResolutionKind.NodeJs,
381
  skipLibCheck: true,
382
  isolatedModules: true
383
};
384

385
// React application
386
const reactConfig: ts.CompilerOptions = {
387
  target: ts.ScriptTarget.ES2018,
388
  module: ts.ModuleKind.ESNext,
389
  jsx: ts.JsxEmit.ReactJSX,
390
  jsxImportSource: "react",
391
  esModuleInterop: true,
392
  allowSyntheticDefaultImports: true,
393
  skipLibCheck: true,
394
  isolatedModules: true
395
};
396

397
// Library build (multiple targets)
398
const libConfig: ts.CompilerOptions = {
399
  target: ts.ScriptTarget.ES5,
400
  module: ts.ModuleKind.UMD,
401
  declaration: true,
402
  sourceMap: true,
403
  skipLibCheck: true
404
};
405
```
406

407
## Types
408

409
### Transpilation Types
410

411
```typescript { .api }
412
type MapLike<T> = Record<string, T>;
413

414
interface Diagnostic {
415
  file: SourceFile | undefined;
416
  start: number | undefined;
417
  length: number | undefined;
418
  messageText: string | DiagnosticMessageChain;
419
  category: DiagnosticCategory;
420
  code: number;
421
}
422

423
enum DiagnosticCategory {
424
  Warning = 0,
425
  Error = 1,
426
  Suggestion = 2,
427
  Message = 3
428
}
429

430
interface DiagnosticMessageChain {
431
  messageText: string;
432
  category: DiagnosticCategory;
433
  code: number;
434
  next?: DiagnosticMessageChain[];
435
}
436
```
437

438
### Target and Module Types
439

440
```typescript { .api }
441
enum ScriptTarget {
442
  ES3 = 0,
443
  ES5 = 1,
444
  ES2015 = 2,
445
  ES2016 = 3,
446
  ES2017 = 4,
447
  ES2018 = 5,
448
  ES2019 = 6,
449
  ES2020 = 7,
450
  ES2021 = 8,
451
  ES2022 = 9,
452
  ESNext = 99,
453
  Latest = ESNext
454
}
455

456
enum ModuleKind {
457
  None = 0,
458
  CommonJS = 1,
459
  AMD = 2,
460
  UMD = 3,
461
  System = 4,
462
  ES2015 = 5,
463
  ES2020 = 6,
464
  ES2022 = 7,
465
  ESNext = 99,
466
  Node16 = 100,
467
  NodeNext = 199
468
}
469

470
enum ModuleResolutionKind {
471
  Classic = 1,
472
  NodeJs = 2,
473
  Node16 = 3,
474
  NodeNext = 99
475
}
476
```
477

478
### Performance Considerations
479

480
Transpilation is designed for speed over completeness:
481

482
- **No type checking**: Only syntactic transformations are performed
483
- **Single file processing**: Each file is processed independently
484
- **Limited diagnostics**: Only syntax errors and basic semantic errors are reported
485
- **Fast parsing**: Optimized for development-time performance
486
- **Incremental friendly**: Suitable for watch mode and hot reload scenarios
487

488
For full type checking and comprehensive error reporting, use the full compiler API with `createProgram()` and `program.emit()`.