0
# CLI Tool
1

2
Command-line interface for directly executing TypeScript files with full jiti transformation support.
3

4
## Capabilities
5

6
### jiti Command
7

8
Execute TypeScript and other supported files directly from the command line without compilation.
9

10
```bash
11
# CLI Usage
12
jiti <path> [...arguments]
13
```
14

15
**Usage Examples:**
16

17
```bash
18
# Execute a TypeScript file
19
jiti ./script.ts
20

21
# Execute with arguments
22
jiti ./cli-tool.ts --config ./config.json --verbose
23

24
# Execute from npm script
25
npm exec jiti ./build-script.ts
26

27
# Global installation
28
npm install -g jiti
29
jiti ./any-script.ts
30
```
31

32
### CLI Features
33

34
**Automatic File Type Detection:**
35
The CLI automatically handles various file extensions and applies appropriate transformations:
36

37
```bash
38
# All of these work seamlessly
39
jiti ./config.ts        # TypeScript
40
jiti ./script.mts       # TypeScript ESM
41
jiti ./legacy.cts       # TypeScript CommonJS  
42
jiti ./component.tsx    # TypeScript + JSX
43
jiti ./regular.js       # JavaScript
44
jiti ./module.mjs       # JavaScript ESM
45
jiti ./common.cjs       # JavaScript CommonJS
46
```
47

48
**Node.js Integration:**
49
- Preserves Node.js command-line arguments and environment
50
- Maintains proper `process.argv` handling
51
- Supports Node.js debugging and profiling flags
52

53
**Performance Optimization:**
54
- Enables Node.js compile cache when available (Node.js 22.8+)
55
- Uses filesystem caching for repeated executions
56
- Smart transformation detection to avoid unnecessary processing
57

58
### Environment Configuration
59

60
Configure jiti CLI behavior using environment variables:
61

62
```bash
63
# Enable debug mode
64
JITI_DEBUG=1 jiti ./script.ts
65

66
# Enable JSX support
67
JITI_JSX=1 jiti ./component.tsx
68

69
# Disable filesystem caching
70
JITI_FS_CACHE=false jiti ./dev-script.ts
71

72
# Custom aliases
73
JITI_ALIAS='{"@/*": "./src/*"}' jiti ./script.ts
74

75
# Multiple options
76
JITI_DEBUG=1 JITI_JSX=1 JITI_SOURCE_MAPS=1 jiti ./complex-script.tsx
77
```
78

79
### Integration with Development Workflows
80

81
**Package.json Scripts:**
82

83
```json
84
{
85
  "scripts": {
86
    "dev": "jiti ./src/dev-server.ts",
87
    "build": "jiti ./scripts/build.ts",
88
    "test": "jiti ./scripts/test-runner.ts",
89
    "setup": "jiti ./scripts/setup.ts --init",
90
    "deploy": "NODE_ENV=production jiti ./scripts/deploy.ts"
91
  }
92
}
93
```
94

95
**Development Server:**
96

97
```typescript
98
// dev-server.ts
99
import express from "express";
100
import { config } from "./config.ts";
101

102
const app = express();
103

104
app.get("/", (req, res) => {
105
  res.json({ message: "Development server running" });
106
});
107

108
app.listen(config.port, () => {
109
  console.log(`Server running on port ${config.port}`);
110
});
111
```
112

113
```bash
114
# Run development server directly
115
jiti ./dev-server.ts
116
```
117

118
**Build Scripts:**
119

120
```typescript
121
// scripts/build.ts
122
import { execSync } from "child_process";
123
import { readFileSync, writeFileSync } from "fs";
124
import { BuildConfig } from "./types.ts";
125

126
const config: BuildConfig = {
127
  entry: "./src/index.ts",
128
  output: "./dist/bundle.js",
129
  minify: process.env.NODE_ENV === "production"
130
};
131

132
console.log("Building application...");
133
execSync(`esbuild ${config.entry} --bundle --outfile=${config.output}`);
134
console.log("Build complete!");
135
```
136

137
```bash
138
# Execute build script
139
jiti ./scripts/build.ts
140
```
141

142
### Advanced CLI Usage
143

144
**With Node.js Flags:**
145

146
```bash
147
# Debug mode
148
node --inspect --loader jiti/loader ./script.ts
149

150
# Memory profiling
151
node --max-old-space-size=4096 $(which jiti) ./memory-intensive.ts
152

153
# ES modules with experimental features
154
node --experimental-modules $(which jiti) ./esm-script.ts
155
```
156

157
**Complex Project Setup:**
158

159
```typescript
160
// scripts/setup.ts
161
import { existsSync, mkdirSync, writeFileSync } from "fs";
162
import { join } from "path";
163
import { Config } from "../src/types.ts";
164

165
interface SetupOptions {
166
  init?: boolean;
167
  config?: string;
168
  force?: boolean;
169
}
170

171
const args = process.argv.slice(2);
172
const options: SetupOptions = {
173
  init: args.includes("--init"),
174
  config: args.find(arg => arg.startsWith("--config="))?.split("=")[1],
175
  force: args.includes("--force")
176
};
177

178
async function setup() {
179
  console.log("Setting up project...");
180
  
181
  if (options.init) {
182
    const configPath = options.config || "./config.json";
183
    const defaultConfig: Config = {
184
      apiUrl: "http://localhost:3000",
185
      timeout: 5000
186
    };
187
    
188
    if (!existsSync(configPath) || options.force) {
189
      writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
190
      console.log(`Created config: ${configPath}`);
191
    }
192
  }
193
  
194
  // Additional setup logic...
195
  console.log("Setup complete!");
196
}
197

198
setup().catch(console.error);
199
```
200

201
```bash
202
# Run setup with options
203
jiti ./scripts/setup.ts --init --config=./custom-config.json --force
204
```
205

206
### Error Handling and Debugging
207

208
**Runtime Error Handling:**
209

210
```typescript
211
// error-prone-script.ts
212
try {
213
  const data = await import("./non-existent-config.ts");
214
} catch (error) {
215
  console.error("Failed to load config:", error.message);
216
  process.exit(1);
217
}
218
```
219

220
```bash
221
# CLI handles errors gracefully
222
jiti ./error-prone-script.ts
223
# Output: Failed to load config: Cannot resolve module './non-existent-config.ts'
224
# Exit code: 1
225
```
226

227
**Debug Output:**
228

229
```bash
230
# Enable debug output to see transformation details
231
JITI_DEBUG=1 jiti ./script.ts
232
```
233

234
Debug output includes:
235
- File resolution paths
236
- Transformation decisions
237
- Cache usage information
238
- Performance timings
239

240
### Testing and Continuous Integration
241

242
**Test Runner Integration:**
243

244
```typescript
245
// scripts/test-runner.ts
246
import { execSync } from "child_process";
247
import { globSync } from "glob";
248

249
const testFiles = globSync("./tests/**/*.test.ts");
250

251
for (const testFile of testFiles) {
252
  console.log(`Running: ${testFile}`);
253
  try {
254
    execSync(`jiti ${testFile}`, { stdio: "inherit" });
255
  } catch (error) {
256
    console.error(`Test failed: ${testFile}`);
257
    process.exit(1);
258
  }
259
}
260

261
console.log("All tests passed!");
262
```
263

264
**CI/CD Integration:**
265

266
```yaml
267
# .github/workflows/test.yml
268
name: Test
269
on: [push, pull_request]
270

271
jobs:
272
  test:
273
    runs-on: ubuntu-latest
274
    steps:
275
      - uses: actions/checkout@v3
276
      - uses: actions/setup-node@v3
277
        with:
278
          node-version: '20'
279
      - run: npm install
280
      - run: npx jiti ./scripts/test-runner.ts
281
      - run: npx jiti ./scripts/lint-check.ts
282
      - run: npx jiti ./scripts/build-check.ts
283
```
284

285
**Docker Integration:**
286

287
```dockerfile
288
# Dockerfile
289
FROM node:20-alpine
290

291
WORKDIR /app
292
COPY package*.json ./
293
RUN npm install
294

295
COPY . .
296

297
# Use jiti to run TypeScript directly
298
CMD ["npx", "jiti", "./src/server.ts"]
299
```
300

301
### Performance Considerations
302

303
**Caching for CLI:**
304

305
```bash
306
# First run: slower (transformation + caching)
307
time jiti ./large-script.ts
308
# real    0m2.345s
309

310
# Subsequent runs: faster (cached)
311
time jiti ./large-script.ts  
312
# real    0m0.456s
313
```
314

315
**Production Usage:**
316

317
For production deployments, consider pre-compiling TypeScript:
318

319
```json
320
{
321
  "scripts": {
322
    "build": "tsc",
323
    "start": "node ./dist/server.js",
324
    "dev": "jiti ./src/server.ts"
325
  }
326
}
327
```
328

329
**Memory Usage:**
330

331
```bash
332
# Monitor memory usage for large scripts
333
NODE_OPTIONS="--max-old-space-size=2048" jiti ./memory-intensive.ts
334
```
335

336
### Comparison with Alternatives
337

338
**vs ts-node:**
339

340
```bash
341
# ts-node
342
npx ts-node ./script.ts
343

344
# jiti - simpler, faster startup
345
npx jiti ./script.ts
346
```
347

348
**vs tsx:**
349

350
```bash
351
# tsx
352
npx tsx ./script.ts
353

354
# jiti - more configuration options
355
JITI_DEBUG=1 npx jiti ./script.ts
356
```
357

358
**Advantages of jiti CLI:**
359
- Zero configuration required
360
- Built-in caching system
361
- Comprehensive environment variable support
362
- ESM/CommonJS interoperability
363
- JSX support with configuration
364
- Smart transformation detection
365
- Cross-platform compatibility