0
# Transpiler Integration
1

2
Support for alternative transpilers like SWC for faster compilation and experimental features, providing pluggable compilation backends.
3

4
## Capabilities
5

6
### Transpiler Module Interface
7

8
Interface for third-party transpiler modules that can replace TypeScript's compiler.
9

10
```typescript { .api }
11
/**
12
 * Third-party transpiler module interface
13
 */
14
interface TranspilerModule {
15
  /**
16
   * Create a transpiler instance
17
   * @param options - Configuration options for the transpiler
18
   * @returns Transpiler instance
19
   */
20
  create(options: CreateTranspilerOptions): Transpiler;
21
}
22

23
/**
24
 * Options for creating transpiler instances
25
 */
26
interface CreateTranspilerOptions {
27
  /** TypeScript service instance */
28
  service: Service;
29
  /** TypeScript configuration */
30
  config: _ts.ParsedCommandLine;
31
  /** File extension mapping */
32
  nodeModuleEmitKind?: NodeModuleEmitKind;
33
  /** Transform function */
34
  transformers?: _ts.CustomTransformers | ((program: _ts.Program) => _ts.CustomTransformers);
35
}
36

37
/**
38
 * Factory function for creating transpiler instances
39
 */
40
type TranspilerFactory = (options: CreateTranspilerOptions) => Transpiler;
41

42
/**
43
 * Node.js module emit types
44
 */
45
type NodeModuleEmitKind = 'nodeesm' | 'nodecjs';
46
```
47

48
### Transpiler Instance Interface
49

50
Interface for transpiler instances that perform the actual code transformation.
51

52
```typescript { .api }
53
/**
54
 * Transpiler instance interface
55
 */
56
interface Transpiler {
57
  /**
58
   * Transpile TypeScript code to JavaScript
59
   * @param code - TypeScript source code
60
   * @param options - Transpilation options
61
   * @returns Transpiled output
62
   */
63
  transpile(code: string, options: TranspileOptions): TranspileOutput;
64
}
65

66
/**
67
 * Options for transpilation
68
 */
69
interface TranspileOptions {
70
  /** Source file name */
71
  fileName: string;
72
  /** Line offset for error reporting */
73
  lineOffset?: number;
74
  /** Whether to emit decorators */
75
  experimentalDecorators?: boolean;
76
  /** Target ECMAScript version */
77
  target?: _ts.ScriptTarget;
78
  /** Module format */
79
  module?: _ts.ModuleKind;
80
}
81

82
/**
83
 * Transpiler output interface
84
 */
85
interface TranspileOutput {
86
  /** Transpiled JavaScript code */
87
  outputText: string;
88
  /** Source map if generated */
89
  sourceMapText?: string;
90
  /** Diagnostic messages */
91
  diagnostics?: ReadonlyArray<_ts.Diagnostic>;
92
}
93
```
94

95
### Built-in SWC Transpiler
96

97
Built-in SWC (Speedy Web Compiler) integration for faster TypeScript compilation.
98

99
```typescript { .api }
100
// Available as ts-node/transpilers/swc entry point
101
// Production-ready SWC transpiler integration
102

103
// Available as ts-node/transpilers/swc-experimental entry point  
104
// Experimental SWC features and optimizations
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
import { register } from "ts-node";
111

112
// Use SWC transpiler (recommended)
113
register({
114
  swc: true, // Shorthand for transpiler: 'ts-node/transpilers/swc'
115
  compilerOptions: {
116
    target: "es2020",
117
    module: "commonjs",
118
  }
119
});
120

121
// Use SWC explicitly
122
register({
123
  transpiler: 'ts-node/transpilers/swc',
124
  transpileOnly: true, // Required with custom transpilers
125
});
126

127
// Use experimental SWC features
128
register({
129
  transpiler: 'ts-node/transpilers/swc-experimental',
130
  transpileOnly: true,
131
});
132
```
133

134
## Custom Transpiler Implementation
135

136
### Creating a Custom Transpiler
137

138
```typescript
139
// custom-transpiler.ts
140
import { TranspilerModule, CreateTranspilerOptions, Transpiler } from "ts-node";
141

142
const customTranspilerModule: TranspilerModule = {
143
  create(options: CreateTranspilerOptions): Transpiler {
144
    const { service, config } = options;
145
    
146
    return {
147
      transpile(code: string, transpileOptions: TranspileOptions) {
148
        // Custom transpilation logic
149
        const result = customCompile(code, {
150
          target: transpileOptions.target,
151
          module: transpileOptions.module,
152
          fileName: transpileOptions.fileName,
153
          // Use ts-node's TypeScript configuration
154
          ...config.options
155
        });
156
        
157
        return {
158
          outputText: result.code,
159
          sourceMapText: result.map,
160
          diagnostics: result.diagnostics || []
161
        };
162
      }
163
    };
164
  }
165
};
166

167
module.exports = customTranspilerModule;
168

169
function customCompile(code: string, options: any) {
170
  // Implement your custom compilation logic
171
  // This could use Babel, esbuild, or any other compiler
172
  return {
173
    code: '// Compiled code here',
174
    map: undefined,
175
    diagnostics: []
176
  };
177
}
178
```
179

180
**Usage:**
181

182
```typescript
183
import { register } from "ts-node";
184

185
register({
186
  transpiler: './custom-transpiler.ts',
187
  transpileOnly: true,
188
});
189
```
190

191
### Babel Transpiler Example
192

193
```typescript
194
// babel-transpiler.ts
195
import { TranspilerModule, CreateTranspilerOptions } from "ts-node";
196
import { transform } from "@babel/core";
197

198
const babelTranspilerModule: TranspilerModule = {
199
  create(options: CreateTranspilerOptions) {
200
    return {
201
      transpile(code: string, transpileOptions) {
202
        const result = transform(code, {
203
          filename: transpileOptions.fileName,
204
          presets: [
205
            ['@babel/preset-typescript', {
206
              target: transpileOptions.target
207
            }],
208
            ['@babel/preset-env', {
209
              targets: { node: 'current' }
210
            }]
211
          ],
212
          sourceMaps: true,
213
        });
214
        
215
        return {
216
          outputText: result?.code || '',
217
          sourceMapText: JSON.stringify(result?.map),
218
        };
219
      }
220
    };
221
  }
222
};
223

224
module.exports = babelTranspilerModule;
225
```
226

227
### esbuild Transpiler Example
228

229
```typescript
230
// esbuild-transpiler.ts
231
import { TranspilerModule, CreateTranspilerOptions } from "ts-node";
232
import { transformSync } from "esbuild";
233

234
const esbuildTranspilerModule: TranspilerModule = {
235
  create(options: CreateTranspilerOptions) {
236
    return {
237
      transpile(code: string, transpileOptions) {
238
        const result = transformSync(code, {
239
          loader: 'ts',
240
          target: 'node16',
241
          format: 'cjs',
242
          sourcemap: 'inline',
243
          sourcefile: transpileOptions.fileName,
244
        });
245
        
246
        return {
247
          outputText: result.code,
248
          sourceMapText: undefined, // Inline source map
249
        };
250
      }
251
    };
252
  }
253
};
254

255
module.exports = esbuildTranspilerModule;
256
```
257

258
## Transpiler Configuration
259

260
### SWC Configuration
261

262
```typescript
263
import { register } from "ts-node";
264

265
// SWC with custom configuration
266
register({
267
  transpiler: ['ts-node/transpilers/swc', {
268
    // SWC-specific options
269
    jsc: {
270
      target: 'es2020',
271
      parser: {
272
        syntax: 'typescript',
273
        decorators: true,
274
      },
275
      transform: {
276
        decoratorMetadata: true,
277
      },
278
    },
279
    module: {
280
      type: 'commonjs',
281
    },
282
  }],
283
  transpileOnly: true,
284
});
285
```
286

287
### Environment-Based Transpiler Selection
288

289
```typescript
290
import { register } from "ts-node";
291

292
const isDevelopment = process.env.NODE_ENV === 'development';
293
const useSwc = process.env.USE_SWC === 'true';
294

295
register({
296
  // Use SWC in development for speed, TypeScript in production for accuracy
297
  transpiler: isDevelopment && useSwc ? 'ts-node/transpilers/swc' : undefined,
298
  transpileOnly: isDevelopment,
299
  typeCheck: !isDevelopment,
300
  compilerOptions: {
301
    target: "es2020",
302
    module: "commonjs",
303
    strict: !isDevelopment,
304
  }
305
});
306
```
307

308
## Advanced Transpiler Usage
309

310
### Transpiler with Custom Transformers
311

312
```typescript
313
// transformer-transpiler.ts
314
import { TranspilerModule, CreateTranspilerOptions } from "ts-node";
315
import * as ts from "typescript";
316

317
const transformerTranspilerModule: TranspilerModule = {
318
  create(options: CreateTranspilerOptions) {
319
    const { service } = options;
320
    
321
    // Custom AST transformers
322
    const customTransformers: ts.CustomTransformers = {
323
      before: [
324
        // Add custom before transformers
325
        (context: ts.TransformationContext) => {
326
          return (sourceFile: ts.SourceFile) => {
327
            // Custom AST transformation logic
328
            return sourceFile;
329
          };
330
        }
331
      ],
332
      after: [
333
        // Add custom after transformers
334
      ]
335
    };
336
    
337
    return {
338
      transpile(code: string, transpileOptions) {
339
        // Use TypeScript compiler with custom transformers
340
        const result = ts.transpileModule(code, {
341
          compilerOptions: {
342
            target: transpileOptions.target,
343
            module: transpileOptions.module,
344
          },
345
          transformers: customTransformers,
346
          fileName: transpileOptions.fileName,
347
        });
348
        
349
        return {
350
          outputText: result.outputText,
351
          sourceMapText: result.sourceMapText,
352
          diagnostics: result.diagnostics,
353
        };
354
      }
355
    };
356
  }
357
};
358

359
module.exports = transformerTranspilerModule;
360
```
361

362
### Performance Benchmarking
363

364
```typescript
365
// benchmark-transpiler.ts
366
import { TranspilerModule, CreateTranspilerOptions } from "ts-node";
367
import { performance } from "perf_hooks";
368

369
function createBenchmarkTranspiler(baseTranspiler: string): TranspilerModule {
370
  return {
371
    create(options: CreateTranspilerOptions) {
372
      const baseModule = require(baseTranspiler);
373
      const base = baseModule.create(options);
374
      
375
      return {
376
        transpile(code: string, transpileOptions) {
377
          const start = performance.now();
378
          const result = base.transpile(code, transpileOptions);
379
          const end = performance.now();
380
          
381
          console.log(`Transpiled ${transpileOptions.fileName} in ${end - start}ms`);
382
          
383
          return result;
384
        }
385
      };
386
    }
387
  };
388
}
389

390
module.exports = createBenchmarkTranspiler('ts-node/transpilers/swc');
391
```
392

393
### Transpiler Error Handling
394

395
```typescript
396
// error-handling-transpiler.ts
397
import { TranspilerModule, CreateTranspilerOptions } from "ts-node";
398

399
const errorHandlingTranspilerModule: TranspilerModule = {
400
  create(options: CreateTranspilerOptions) {
401
    const baseModule = require('ts-node/transpilers/swc');
402
    const base = baseModule.create(options);
403
    
404
    return {
405
      transpile(code: string, transpileOptions) {
406
        try {
407
          return base.transpile(code, transpileOptions);
408
        } catch (error) {
409
          console.error(`Transpilation error in ${transpileOptions.fileName}:`, error);
410
          
411
          // Fallback to TypeScript compiler
412
          const ts = require('typescript');
413
          const result = ts.transpileModule(code, {
414
            compilerOptions: {
415
              target: transpileOptions.target,
416
              module: transpileOptions.module,
417
            },
418
            fileName: transpileOptions.fileName,
419
          });
420
          
421
          return {
422
            outputText: result.outputText,
423
            sourceMapText: result.sourceMapText,
424
            diagnostics: result.diagnostics,
425
          };
426
        }
427
      }
428
    };
429
  }
430
};
431

432
module.exports = errorHandlingTranspilerModule;
433
```
434

435
## CLI Integration with Transpilers
436

437
```bash
438
# Use SWC transpiler via CLI
439
ts-node --swc script.ts
440

441
# Use custom transpiler
442
ts-node --transpiler ./custom-transpiler.js script.ts
443

444
# Use transpiler with configuration
445
ts-node --transpiler '[\"./custom-transpiler.js\",{\"option\":\"value\"}]' script.ts
446
```
447

448
```json
449
{
450
  "scripts": {
451
    "dev:swc": "ts-node --swc src/index.ts",
452
    "dev:babel": "ts-node --transpiler ./transpilers/babel-transpiler.js src/index.ts",
453
    "dev:esbuild": "ts-node --transpiler ./transpilers/esbuild-transpiler.js src/index.ts"
454
  }
455
}
456
```