0
# Instance Creation and Configuration
1

2
Core jiti instance creation with comprehensive configuration options for caching, transformation, and module handling.
3

4
## Capabilities
5

6
### createJiti Function
7

8
Creates a new jiti instance with custom options for runtime TypeScript and ESM support.
9

10
```typescript { .api }
11
/**
12
 * Creates a new Jiti instance with custom options.
13
 * @param id - Instance id, usually the current filename or import.meta.url
14
 * @param userOptions - Custom options to override the default options
15
 * @returns A Jiti instance with configured behavior
16
 */
17
function createJiti(id: string, userOptions?: JitiOptions): Jiti;
18
```
19

20
**Usage Examples:**
21

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

25
// Basic usage with current file URL
26
const jiti = createJiti(import.meta.url);
27

28
// With custom options
29
const jiti = createJiti(import.meta.url, {
30
  debug: true,
31
  fsCache: false,
32
  jsx: true
33
});
34

35
// CommonJS usage (deprecated)
36
const { createJiti } = require("jiti");
37
const jiti = createJiti(__filename);
38
```
39

40
### Configuration Options
41

42
Complete configuration interface for customizing jiti behavior.
43

44
```typescript { .api }
45
interface JitiOptions {
46
  /**
47
   * Filesystem source cache - enables caching transformed files to disk
48
   * @default true
49
   */
50
  fsCache?: boolean | string;
51
  
52
  /**
53
   * Rebuild the filesystem source cache
54
   * @default false
55
   */
56
  rebuildFsCache?: boolean;
57
  
58
  /**
59
   * Runtime module cache - integrates with Node.js require.cache
60
   * @default true
61
   */
62
  moduleCache?: boolean;
63
  
64
  /**
65
   * Enable verbose debugging output
66
   * @default false
67
   */
68
  debug?: boolean;
69
  
70
  /**
71
   * Enable sourcemaps for transformed code
72
   * @default false
73
   */
74
  sourceMaps?: boolean;
75
  
76
  /**
77
   * Enable default export interoperability using Proxy
78
   * @default true
79
   */
80
  interopDefault?: boolean;
81
  
82
  /**
83
   * Supported file extensions for transformation
84
   * @default [".js", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts", ".mtsx", ".ctsx", ".json"]
85
   */
86
  extensions?: string[];
87
  
88
  /**
89
   * Custom transform function for source code
90
   */
91
  transform?: (opts: TransformOptions) => TransformResult;
92
  
93
  /**
94
   * Transform options passed to the transform function
95
   */
96
  transformOptions?: Omit<TransformOptions, "source">;
97
  
98
  /**
99
   * Resolve aliases for module paths
100
   * @default {}
101
   */
102
  alias?: Record<string, string>;
103
  
104
  /**
105
   * Modules to always use native require/import for
106
   * @default ["typescript", "jiti"]
107
   */
108
  nativeModules?: string[];
109
  
110
  /**
111
   * Modules to transform regardless of syntax
112
   * @default []
113
   */
114
  transformModules?: string[];
115
  
116
  /**
117
   * Parent module's import.meta context for ESM resolution
118
   */
119
  importMeta?: ImportMeta;
120
  
121
  /**
122
   * Try native require/import before jiti transformations
123
   * @default false (true if Bun is detected)
124
   */
125
  tryNative?: boolean;
126
  
127
  /**
128
   * Enable JSX support using @babel/plugin-transform-react-jsx
129
   * @default false
130
   */
131
  jsx?: boolean | JSXOptions;
132
  
133
  /**
134
   * @deprecated Use the fsCache option instead
135
   * @default true
136
   */
137
  cache?: boolean | string;
138
  
139
  /**
140
   * @deprecated Use the moduleCache option instead
141
   * @default true
142
   */
143
  requireCache?: boolean;
144
  
145
  /**
146
   * Internal cache version for filesystem cache
147
   * @internal
148
   */
149
  cacheVersion?: string;
150
}
151
```
152

153
### Environment Variable Configuration
154

155
All options can be configured via environment variables for convenient runtime configuration.
156

157
**Environment Variables:**
158

159
- `JITI_DEBUG` - Enable debug logging (boolean)
160
- `JITI_FS_CACHE` - Filesystem cache setting (boolean/string)
161
- `JITI_REBUILD_FS_CACHE` - Rebuild cache flag (boolean)
162
- `JITI_MODULE_CACHE` - Module cache setting (boolean)
163
- `JITI_SOURCE_MAPS` - Source maps setting (boolean)
164
- `JITI_INTEROP_DEFAULT` - Default interop setting (boolean)
165
- `JITI_ALIAS` - Resolve aliases (JSON string)
166
- `JITI_NATIVE_MODULES` - Native modules list (JSON string)
167
- `JITI_TRANSFORM_MODULES` - Transform modules list (JSON string)
168
- `JITI_TRY_NATIVE` - Try native first setting (boolean)
169
- `JITI_JSX` - JSX support setting (boolean)
170

171
**Usage Examples:**
172

173
```bash
174
# Enable debug mode and JSX support
175
JITI_DEBUG=1 JITI_JSX=1 node script.js
176

177
# Set custom aliases
178
JITI_ALIAS='{"@/*": "./src/*", "~/*": "./lib/*"}' node script.js
179

180
# Disable caching for development
181
JITI_FS_CACHE=false JITI_MODULE_CACHE=false node script.js
182
```
183

184
### JSX Configuration
185

186
Advanced JSX transformation options using Babel's React JSX plugin.
187

188
```typescript { .api }
189
interface JSXOptions {
190
  /**
191
   * Throw error if JSX namespace is used
192
   * @default false
193
   */
194
  throwIfNamespace?: boolean;
195
  
196
  /**
197
   * JSX runtime mode - 'classic' uses React.createElement, 'automatic' uses new JSX transform
198
   * @default 'classic'
199
   */
200
  runtime?: "classic" | "automatic";
201
  
202
  /**
203
   * Import source for automatic runtime
204
   * @default 'react'
205
   */
206
  importSource?: string;
207
  
208
  /**
209
   * JSX pragma function for classic runtime
210
   * @default 'React.createElement'
211
   */
212
  pragma?: string;
213
  
214
  /**
215
   * JSX fragment pragma for classic runtime
216
   * @default 'React.Fragment'
217
   */
218
  pragmaFrag?: string;
219
  
220
  /**
221
   * Use built-in helpers for JSX
222
   * @default false
223
   */
224
  useBuiltIns?: boolean;
225
  
226
  /**
227
   * Use spread syntax for props
228
   * @default false
229
   */
230
  useSpread?: boolean;
231
}
232
```
233

234
**Usage Examples:**
235

236
```typescript
237
// Enable JSX with default React settings
238
const jiti = createJiti(import.meta.url, { jsx: true });
239

240
// Custom JSX configuration for Preact
241
const jiti = createJiti(import.meta.url, {
242
  jsx: {
243
    runtime: "automatic",
244
    importSource: "preact"
245
  }
246
});
247

248
// Classic JSX with custom pragma
249
const jiti = createJiti(import.meta.url, {
250
  jsx: {
251
    runtime: "classic",
252
    pragma: "h",
253
    pragmaFrag: "Fragment"
254
  }
255
});
256
```
257

258
### Performance and Caching
259

260
jiti provides multiple caching strategies for optimal performance:
261

262
**Filesystem Cache:**
263
- Caches transformed source code to disk
264
- Default location: `node_modules/.cache/jiti` or temp directory
265
- Significantly improves startup time for large projects
266
- Can be customized with string path or disabled entirely
267

268
**Module Cache:**
269
- Integrates with Node.js native `require.cache`
270
- Prevents duplicate module evaluation
271
- Allows hot reloading when disabled
272

273
**Usage Examples:**
274

275
```typescript
276
// Custom filesystem cache directory
277
const jiti = createJiti(import.meta.url, {
278
  fsCache: "./custom-cache"
279
});
280

281
// Disable all caching for development
282
const jiti = createJiti(import.meta.url, {
283
  fsCache: false,
284
  moduleCache: false
285
});
286

287
// Force cache rebuild
288
const jiti = createJiti(import.meta.url, {
289
  rebuildFsCache: true
290
});
291
```