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
```