0
# tsx
1
2
tsx (TypeScript Execute) is a TypeScript execution runtime and CLI tool that enables developers to directly run TypeScript and ESM files in Node.js without requiring a separate compilation step. Built on top of esbuild for fast transpilation, it provides seamless execution of TypeScript code with full support for both CommonJS and ESM modules.
3
4
## Package Information
5
6
- **Package Name**: tsx
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install tsx`
10
11
## Core Imports
12
13
For CommonJS environments:
14
15
```javascript
16
const { register, require } = require("tsx/cjs/api");
17
```
18
19
For ESM environments:
20
21
```typescript
22
import { register, tsImport } from "tsx/esm/api";
23
```
24
25
Direct CLI usage:
26
27
```bash
28
npx tsx script.ts
29
```
30
31
## Basic Usage
32
33
### CLI Execution
34
35
```bash
36
# Run TypeScript files directly
37
tsx hello.ts
38
39
# Watch mode for development
40
tsx watch server.ts
41
42
# REPL mode
43
tsx
44
45
# Eval mode
46
tsx -e "console.log('Hello TypeScript')"
47
```
48
49
### Programmatic CommonJS API
50
51
```javascript
52
const { register } = require("tsx/cjs/api");
53
54
// Register tsx loader
55
const unregister = register();
56
57
// Now you can require TypeScript files
58
const myModule = require("./my-module.ts");
59
60
// Unregister when done
61
unregister();
62
```
63
64
### Programmatic ESM API
65
66
```typescript
67
import { register, tsImport } from "tsx/esm/api";
68
69
// Register tsx loader for ESM
70
const unregister = register();
71
72
// Import TypeScript modules
73
const myModule = await tsImport("./my-module.ts", import.meta.url);
74
75
// Unregister when done
76
await unregister();
77
```
78
79
## Architecture
80
81
tsx is built around several key components:
82
83
- **CLI Interface**: Command-line tool with support for direct execution, watch mode, and REPL
84
- **CommonJS Loader**: Module registration system for CommonJS environments
85
- **ESM Loader**: Hook-based loader system for ESM environments using Node.js module.register()
86
- **Transform Engine**: Uses esbuild for fast TypeScript-to-JavaScript transformation
87
- **Caching System**: Built-in caching for improved performance on subsequent runs
88
- **Source Map Support**: Full source map integration for debugging TypeScript code
89
90
## Capabilities
91
92
### CLI Operations
93
94
Command-line interface for direct TypeScript execution with watch mode, REPL, and evaluation capabilities.
95
96
```bash { .api }
97
tsx [options] [script] [script-args...]
98
tsx watch [options] [script] [script-args...]
99
```
100
101
[CLI Usage](./cli.md)
102
103
### CommonJS API
104
105
Registration system for enabling TypeScript support in CommonJS modules with scoped require functionality.
106
107
```javascript { .api }
108
const { register, require } = require("tsx/cjs/api");
109
110
function register(options?: RegisterOptions): Unregister;
111
function register(options: RequiredProperty<RegisterOptions, 'namespace'>): NamespacedUnregister;
112
113
function require(id: string, fromFile: string | URL): any;
114
```
115
116
[CommonJS API](./cjs-api.md)
117
118
### ESM API
119
120
Hook-based loader system for ESM environments with dynamic import capabilities and advanced configuration options.
121
122
```typescript { .api }
123
import { register, tsImport, type RegisterOptions } from "tsx/esm/api";
124
125
function register(options?: RegisterOptions): Unregister;
126
function register(options: RequiredProperty<RegisterOptions, 'namespace'>): NamespacedUnregister;
127
128
function tsImport(specifier: string, options: string | TsImportOptions): Promise<any>;
129
130
interface RegisterOptions {
131
namespace?: string;
132
onImport?: (url: string) => void;
133
tsconfig?: TsconfigOptions;
134
}
135
136
type TsconfigOptions = false | string;
137
type Unregister = () => Promise<void>;
138
139
interface TsImportOptions {
140
parentURL: string;
141
onImport?: (url: string) => void;
142
tsconfig?: TsconfigOptions;
143
}
144
```
145
146
[ESM API](./esm-api.md)
147
148
### Main Loader
149
150
Default export that automatically registers both CommonJS and ESM transformation hooks.
151
152
```typescript { .api }
153
import "tsx";
154
// or
155
require("tsx");
156
```
157
158
This automatically enables TypeScript transformation for the entire process without explicit registration calls.
159
160
### Warning Suppression
161
162
Suppress Node.js experimental feature warnings related to ESM loaders and import assertions.
163
164
```javascript { .api }
165
require("tsx/suppress-warnings");
166
```
167
168
**Note**: This entry point is deprecated and will be removed in the next major version. Use `tsx/preflight` instead.
169
170
### Preflight Module
171
172
Preflight module that sets up tsx for use with Node.js `--require` flag, enabling TypeScript support for subsequent `--require` modules.
173
174
```javascript { .api }
175
require("tsx/preflight");
176
```
177
178
Usage with Node.js flags:
179
```bash
180
node --require tsx/preflight --require ./my-typescript-config.ts app.js
181
```
182
183
This module:
184
- Registers CommonJS TypeScript transformation
185
- Suppresses ESM loader warnings
186
- Sets up signal handling for watch mode and IPC communication
187
- Only executes in the main thread to avoid loader conflicts
188
189
### REPL Enhancement
190
191
Patch Node.js REPL to support TypeScript syntax in interactive mode.
192
193
```javascript { .api }
194
require("tsx/patch-repl");
195
```
196
197
When required, this automatically patches the Node.js REPL to support TypeScript transformation.
198
199
### Standalone REPL
200
201
Standalone TypeScript REPL that can be executed directly.
202
203
```javascript { .api }
204
// Available as entry point: tsx/repl
205
```
206
207
**Note**: This entry point is deprecated and will be removed in the next major version. Use `tsx` command without arguments for REPL mode instead.
208
209
Usage:
210
```bash
211
node tsx/repl
212
# or via direct execution of tsx/repl entry point
213
```
214
215
## Types
216
217
### Common Types
218
219
```typescript { .api }
220
type RequiredProperty<Type, Keys extends keyof Type> = Type & { [P in Keys]-?: Type[P] };
221
222
type NodeError = Error & {
223
code: string;
224
url?: string;
225
path?: string;
226
};
227
```