0
# jiti
1
2
jiti provides seamless runtime TypeScript and ESM support for Node.js with zero configuration. It enables importing TypeScript files directly in Node.js applications without a build step, offering both asynchronous and synchronous APIs for maximum compatibility between ESM and CommonJS modules.
3
4
## Package Information
5
6
- **Package Name**: jiti
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install jiti`
10
11
## Core Imports
12
13
```typescript
14
import { createJiti } from "jiti";
15
// or default import (deprecated)
16
import createJiti from "jiti";
17
```
18
19
For CommonJS:
20
21
```javascript
22
const { createJiti } = require("jiti");
23
// or default import (deprecated)
24
const createJiti = require("jiti");
25
```
26
27
## Basic Usage
28
29
```typescript
30
import { createJiti } from "jiti";
31
32
// Create a jiti instance
33
const jiti = createJiti(import.meta.url);
34
35
// Import TypeScript files asynchronously (recommended)
36
const config = await jiti.import("./config.ts");
37
const utils = await jiti.import("./utils.ts", { default: true }); // Get default export
38
39
// Resolve module paths with ESM conditions
40
const resolved = jiti.esmResolve("./some-module");
41
```
42
43
For CommonJS (deprecated but supported):
44
45
```javascript
46
const { createJiti } = require("jiti");
47
48
const jiti = createJiti(__filename);
49
50
// Synchronous import (deprecated)
51
const config = jiti("./config.ts");
52
```
53
54
## Architecture
55
56
jiti is built around several key components:
57
58
- **Instance Creation**: `createJiti()` creates configured instances with custom options
59
- **Async Import API**: Modern `import()` style API for loading modules with TypeScript support
60
- **Transform Engine**: Babel-based transformation for TypeScript, JSX, and ESM syntax
61
- **Cache System**: Filesystem and memory caching for optimal performance
62
- **Resolution System**: Smart module resolution with alias support and ESM/CommonJS interoperability
63
- **ESM Loader**: Global Node.js loader registration for automatic TypeScript support
64
- **Native Mode**: Lightweight mode using runtime import.meta.resolve and dynamic import()
65
66
## Capabilities
67
68
### Instance Creation and Configuration
69
70
Core jiti instance creation with comprehensive configuration options for caching, transformation, and module handling.
71
72
```typescript { .api }
73
function createJiti(id: string, userOptions?: JitiOptions): Jiti;
74
75
interface JitiOptions {
76
fsCache?: boolean | string;
77
rebuildFsCache?: boolean;
78
moduleCache?: boolean;
79
debug?: boolean;
80
sourceMaps?: boolean;
81
interopDefault?: boolean;
82
extensions?: string[];
83
alias?: Record<string, string>;
84
nativeModules?: string[];
85
transformModules?: string[];
86
jsx?: boolean | JSXOptions;
87
tryNative?: boolean;
88
}
89
```
90
91
[Instance Creation and Configuration](./instance-creation.md)
92
93
### Module Import and Resolution
94
95
Modern asynchronous module importing with TypeScript support and advanced resolution capabilities.
96
97
```typescript { .api }
98
interface Jiti {
99
import<T>(
100
id: string,
101
opts?: JitiResolveOptions & { default?: true }
102
): Promise<T>;
103
104
esmResolve(id: string, opts?: JitiResolveOptions): string;
105
}
106
107
interface JitiResolveOptions {
108
conditions?: string[];
109
parentURL?: string | URL;
110
try?: boolean;
111
}
112
```
113
114
[Module Import and Resolution](./module-import.md)
115
116
### Source Code Transformation
117
118
Babel-based source code transformation for TypeScript, JSX, and ESM syntax with comprehensive options.
119
120
```typescript { .api }
121
interface Jiti {
122
transform(opts: TransformOptions): string;
123
evalModule(source: string, options?: EvalModuleOptions): unknown;
124
}
125
126
interface TransformOptions {
127
source: string;
128
filename?: string;
129
ts?: boolean;
130
retainLines?: boolean;
131
interopDefault?: boolean;
132
async?: boolean;
133
jsx?: boolean | JSXOptions;
134
babel?: Record<string, any>;
135
}
136
137
interface TransformResult {
138
code: string;
139
error?: any;
140
}
141
```
142
143
[Source Code Transformation](./transformation.md)
144
145
### Global Registration and ESM Loader
146
147
Global ESM loader registration and native runtime mode for seamless TypeScript support across Node.js applications.
148
149
```typescript { .api }
150
// Import for global registration
151
import "jiti/register";
152
153
// Native mode with limited API
154
import { createJiti } from "jiti/native";
155
```
156
157
[Global Registration and ESM Loader](./global-registration.md)
158
159
### CLI Tool
160
161
Command-line interface for directly executing TypeScript files with full jiti transformation support.
162
163
```bash
164
# CLI usage
165
jiti <path> [...arguments]
166
```
167
168
[CLI Tool](./cli-tool.md)
169
170
## Legacy API (Deprecated)
171
172
```typescript { .api }
173
interface Jiti extends NodeRequire {
174
// Deprecated synchronous import
175
(id: string): any;
176
177
// Deprecated CommonJS resolution
178
resolve: {
179
(id: string, options?: { paths?: string[] }): string;
180
paths(request: string): string[] | null;
181
};
182
183
// Deprecated CommonJS properties
184
cache: ModuleCache;
185
extensions: Record<string, Function>;
186
main: NodeModule | undefined;
187
}
188
```
189
190
**Note:** Synchronous APIs are deprecated. Use `await jiti.import()` instead of `jiti()` for better compatibility.
191
192
## Types
193
194
```typescript { .api }
195
interface JSXOptions {
196
throwIfNamespace?: boolean;
197
runtime?: "classic" | "automatic";
198
importSource?: string;
199
pragma?: string;
200
pragmaFrag?: string;
201
useBuiltIns?: boolean;
202
useSpread?: boolean;
203
}
204
205
interface EvalModuleOptions {
206
id?: string;
207
filename?: string;
208
ext?: string;
209
cache?: ModuleCache;
210
async?: boolean;
211
forceTranspile?: boolean;
212
}
213
214
interface NodeModule {
215
isPreloading: boolean;
216
exports: any;
217
require: NodeRequire;
218
id: string;
219
filename: string;
220
loaded: boolean;
221
parent: NodeModule | null | undefined;
222
children: NodeModule[];
223
path: string;
224
paths: string[];
225
}
226
227
type ModuleCache = Record<string, NodeModule>;
228
```