0
# Source Code Transformation
1

2
Babel-based source code transformation for TypeScript, JSX, and ESM syntax with comprehensive options.
3

4
## Capabilities
5

6
### Transform Function
7

8
Direct source code transformation using jiti's internal Babel-based transform engine.
9

10
```typescript { .api }
11
/**
12
 * Transform source code using jiti's transformation pipeline
13
 * @param opts - Transformation options including source code and configuration
14
 * @returns Transformed source code string
15
 */
16
transform(opts: TransformOptions): string;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { createJiti } from "jiti";
23

24
const jiti = createJiti(import.meta.url);
25

26
// Transform TypeScript to JavaScript
27
const transformed = jiti.transform({
28
  source: `
29
    interface Config {
30
      apiKey: string;
31
    }
32
    export const config: Config = { apiKey: "secret" };
33
  `,
34
  filename: "config.ts",
35
  ts: true
36
});
37

38
// Transform JSX
39
const jsxTransformed = jiti.transform({
40
  source: `
41
    import React from "react";
42
    export const App = () => <div>Hello World</div>;
43
  `,
44
  filename: "App.tsx",
45
  jsx: true
46
});
47

48
// Transform with custom Babel options
49
const customTransformed = jiti.transform({
50
  source: "const x: number = 42;",
51
  filename: "example.ts",
52
  babel: {
53
    plugins: ["@babel/plugin-proposal-decorators"]
54
  }
55
});
56
```
57

58
### Transform Options
59

60
Comprehensive configuration for source code transformation behavior.
61

62
```typescript { .api }
63
interface TransformOptions {
64
  /**
65
   * Source code to transform
66
   */
67
  source: string;
68
  
69
  /**
70
   * Filename for the source (used for sourcemaps and error reporting)
71
   */
72
  filename?: string;
73
  
74
  /**
75
   * Enable TypeScript transformation
76
   * @default Inferred from filename extension
77
   */
78
  ts?: boolean;
79
  
80
  /**
81
   * Retain original line numbers in transformed code
82
   * @default false
83
   */
84
  retainLines?: boolean;
85
  
86
  /**
87
   * Enable default export interoperability
88
   * @default true
89
   */
90
  interopDefault?: boolean;
91
  
92
  /**
93
   * Enable async transformation for ESM modules
94
   * @default false
95
   */
96
  async?: boolean;
97
  
98
  /**
99
   * Enable JSX transformation
100
   * @default false
101
   */
102
  jsx?: boolean | JSXOptions;
103
  
104
  /**
105
   * Custom Babel configuration options
106
   */
107
  babel?: Record<string, any>;
108
}
109
```
110

111
### Transform Result
112

113
Result interface for transformation operations.
114

115
```typescript { .api }
116
interface TransformResult {
117
  /**
118
   * Transformed source code
119
   */
120
  code: string;
121
  
122
  /**
123
   * Transformation error if any occurred
124
   */
125
  error?: any;
126
}
127
```
128

129
### Module Evaluation
130

131
Execute transformed source code as a module within jiti's runtime environment.
132

133
```typescript { .api }
134
/**
135
 * Evaluate transformed code as a module
136
 * @param source - Source code to evaluate (should be pre-transformed)
137
 * @param options - Evaluation options for module context
138
 * @returns Module evaluation result
139
 */
140
evalModule(source: string, options?: EvalModuleOptions): unknown;
141
```
142

143
**Usage Examples:**
144

145
```typescript
146
import { createJiti } from "jiti";
147

148
const jiti = createJiti(import.meta.url);
149

150
// Transform and evaluate TypeScript
151
const source = `
152
  export const getMessage = (name: string): string => {
153
    return \`Hello, \${name}!\`;
154
  };
155
`;
156

157
const transformed = jiti.transform({
158
  source,
159
  filename: "greeting.ts",
160
  ts: true
161
});
162

163
const module = jiti.evalModule(transformed, {
164
  filename: "greeting.ts",
165
  async: true
166
});
167

168
console.log(module.getMessage("World")); // "Hello, World!"
169
```
170

171
### Evaluation Options
172

173
Configuration options for module evaluation context.
174

175
```typescript { .api }
176
interface EvalModuleOptions {
177
  /**
178
   * Module identifier for the evaluated code
179
   */
180
  id?: string;
181
  
182
  /**
183
   * Filename for the module (used in stack traces)
184
   */
185
  filename?: string;
186
  
187
  /**
188
   * File extension for the module
189
   */
190
  ext?: string;
191
  
192
  /**
193
   * Module cache to use for caching the evaluated module
194
   */
195
  cache?: ModuleCache;
196
  
197
  /**
198
   * Enable async module evaluation
199
   * @default true
200
   */
201
  async?: boolean;
202
  
203
  /**
204
   * Force transpilation even if not needed
205
   * @default false
206
   */
207
  forceTranspile?: boolean;
208
}
209
```
210

211
### Advanced Transformation Features
212

213
**TypeScript Metadata and Decorators:**
214

215
```typescript
216
// Transform TypeScript with experimental decorators
217
const decoratorCode = jiti.transform({
218
  source: `
219
    import "reflect-metadata";
220
    
221
    @Entity("users")
222
    class User {
223
      @Column("varchar")
224
      name: string;
225
      
226
      @Column("int")
227
      age: number;
228
    }
229
    
230
    export { User };
231
  `,
232
  filename: "user.ts",
233
  ts: true,
234
  babel: {
235
    plugins: [
236
      ["@babel/plugin-proposal-decorators", { legacy: true }],
237
      ["babel-plugin-transform-typescript-metadata"]
238
    ]
239
  }
240
});
241
```
242

243
**JSX with Custom Runtime:**
244

245
```typescript
246
// Transform JSX for Preact
247
const preactJSX = jiti.transform({
248
  source: `
249
    import { Component } from "preact";
250
    
251
    export class App extends Component {
252
      render() {
253
        return <div>Hello from Preact!</div>;
254
      }
255
    }
256
  `,
257
  filename: "App.tsx",
258
  jsx: {
259
    runtime: "automatic",
260
    importSource: "preact"
261
  }
262
});
263

264
// Transform JSX with classic pragma
265
const customJSX = jiti.transform({
266
  source: `export const element = <div>Custom JSX</div>;`,
267
  filename: "element.tsx",
268
  jsx: {
269
    runtime: "classic",
270
    pragma: "h",
271
    pragmaFrag: "Fragment"
272
  }
273
});
274
```
275

276
**ESM and Import Transformations:**
277

278
```typescript
279
// Transform ESM imports for compatibility
280
const esmCode = jiti.transform({
281
  source: `
282
    import { readFile } from "fs/promises";
283
    import config from "./config.json";
284
    
285
    export async function loadConfig() {
286
      const data = await readFile("./data.txt", "utf8");
287
      return { ...config, data };
288
    }
289
  `,
290
  filename: "loader.ts",
291
  async: true,
292
  interopDefault: true
293
});
294
```
295

296
### Integration with File System
297

298
**Transform Files Directly:**
299

300
```typescript
301
import { readFileSync } from "fs";
302
import { createJiti } from "jiti";
303

304
const jiti = createJiti(import.meta.url);
305

306
// Read and transform a TypeScript file
307
const sourceCode = readFileSync("./src/utils.ts", "utf8");
308
const transformed = jiti.transform({
309
  source: sourceCode,
310
  filename: "./src/utils.ts",
311
  ts: true,
312
  retainLines: true // Preserve line numbers for debugging
313
});
314

315
// Write transformed code or use directly
316
console.log(transformed);
317
```
318

319
**Custom Transform Pipeline:**
320

321
```typescript
322
// Create a custom transformation pipeline
323
function transformTypeScript(filename: string): string {
324
  const source = readFileSync(filename, "utf8");
325
  
326
  return jiti.transform({
327
    source,
328
    filename,
329
    ts: true,
330
    retainLines: process.env.NODE_ENV === "development",
331
    babel: {
332
      // Custom Babel configuration
333
      presets: [
334
        ["@babel/preset-typescript", { allowDeclareFields: true }]
335
      ],
336
      plugins: [
337
        "@babel/plugin-syntax-decorators",
338
        "@babel/plugin-transform-class-properties"
339
      ]
340
    }
341
  });
342
}
343
```
344

345
### Error Handling and Debugging
346

347
**Transformation Error Handling:**
348

349
```typescript
350
try {
351
  const result = jiti.transform({
352
    source: "invalid typescript syntax: const x: = 42;",
353
    filename: "invalid.ts",
354
    ts: true
355
  });
356
} catch (error) {
357
  console.error("Transformation failed:", error.message);
358
  console.error("Location:", error.loc);
359
  console.error("Code frame:", error.codeFrame);
360
}
361
```
362

363
**Source Maps for Debugging:**
364

365
```typescript
366
// Enable source maps for better debugging
367
const jiti = createJiti(import.meta.url, {
368
  sourceMaps: true,
369
  debug: true
370
});
371

372
const transformed = jiti.transform({
373
  source: "const x: number = 42; console.log(x);",
374
  filename: "debug.ts",
375
  ts: true,
376
  retainLines: true
377
});
378

379
// Transformed code will include inline source maps
380
console.log(transformed.includes("//# sourceMappingURL=")); // true
381
```
382

383
### Performance Considerations
384

385
**Caching Transformed Code:**
386

387
```typescript
388
// jiti automatically caches transformed code to filesystem
389
// You can control caching behavior:
390

391
const jiti = createJiti(import.meta.url, {
392
  fsCache: true, // Enable filesystem caching
393
  rebuildFsCache: false // Don't rebuild existing cache
394
});
395

396
// First transform is slow (actual transformation)
397
const result1 = jiti.transform({
398
  source: complexTypeScriptCode,
399
  filename: "complex.ts"
400
});
401

402
// Subsequent transforms are fast (cached)
403
const result2 = jiti.transform({
404
  source: complexTypeScriptCode,
405
  filename: "complex.ts"
406
});
407
```
408

409
**Batch Transformations:**
410

411
```typescript
412
// Transform multiple files efficiently
413
const files = ["config.ts", "utils.ts", "types.ts"];
414
const transformedFiles = files.map(filename => {
415
  const source = readFileSync(filename, "utf8");
416
  return {
417
    filename,
418
    transformed: jiti.transform({
419
      source,
420
      filename,
421
      ts: true
422
    })
423
  };
424
});
425
```