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