0
# ts-node
1

2
ts-node is a TypeScript execution environment and REPL for Node.js that enables direct execution of TypeScript files without precompilation. It works by JIT-transforming TypeScript into JavaScript using Node.js module loading APIs, making it seamlessly integrate with other Node.js tools and libraries.
3

4
## Package Information
5

6
- **Package Name**: ts-node
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install ts-node`
10

11
## Core Imports
12

13
```typescript
14
import { register, create, Service, CreateOptions } from "ts-node";
15
import type * as _ts from "typescript";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { register, create } = require("ts-node");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { register } from "ts-node";
28

29
// Register ts-node globally to handle .ts files
30
const service = register({
31
  transpileOnly: true,
32
  compilerOptions: {
33
    target: "es2020",
34
    module: "commonjs",
35
  },
36
});
37

38
// Now you can require/import .ts files directly
39
const myModule = require("./my-typescript-file.ts");
40
```
41

42
## Architecture
43

44
ts-node is built around several key components:
45

46
- **Service Interface**: Core compilation and registration system (`Service`, `register`, `create`)
47
- **Module Loaders**: CommonJS and ESM integration hooks for transparent TypeScript execution
48
- **REPL Environment**: Interactive TypeScript REPL with support for top-level await
49
- **CLI Tools**: Command-line executables for various execution modes
50
- **Transpiler Integration**: Support for alternative transpilers like SWC for faster compilation
51
- **Configuration System**: Deep integration with TypeScript's tsconfig.json and compiler options
52

53
## Capabilities
54

55
### Core Service Management
56

57
Core functionality for creating and registering TypeScript compilation services. This is the primary API for programmatic usage.
58

59
```typescript { .api }
60
function register(opts?: RegisterOptions): Service;
61
function register(service: Service): Service;
62
function create(rawOptions?: CreateOptions): Service;
63

64
interface Service {
65
  ts: TSCommon;
66
  config: _ts.ParsedCommandLine;
67
  options: RegisterOptions;
68
  enabled(enabled?: boolean): boolean;
69
  ignored(fileName: string): boolean;
70
  compile(code: string, fileName: string, lineOffset?: number): string;
71
  getTypeInfo(code: string, fileName: string, position: number): TypeInfo;
72
}
73
```
74

75
[Core Service Management](./core-service.md)
76

77
### Configuration Options
78

79
Comprehensive configuration system supporting all TypeScript compiler options plus ts-node specific features.
80

81
```typescript { .api }
82
interface CreateOptions {
83
  cwd?: string;
84
  emit?: boolean;
85
  scope?: boolean;
86
  scopeDir?: string;
87
  pretty?: boolean;
88
  transpileOnly?: boolean;
89
  typeCheck?: boolean;
90
  compilerHost?: boolean;
91
  logError?: boolean;
92
  files?: boolean;
93
  compiler?: string;
94
  transpiler?: string | [string, object];
95
  swc?: boolean;
96
  ignore?: string[];
97
  project?: string;
98
  projectSearchDir?: string;
99
  skipProject?: boolean;
100
  skipIgnore?: boolean;
101
  compilerOptions?: object;
102
  ignoreDiagnostics?: Array<number | string>;
103
  require?: Array<string>;
104
  experimentalReplAwait?: boolean;
105
  moduleTypes?: ModuleTypes;
106
  esm?: boolean;
107
  preferTsExts?: boolean;
108
  experimentalSpecifierResolution?: 'node' | 'explicit';
109
  experimentalTsImportSpecifiers?: boolean;
110
}
111
```
112

113
[Configuration Options](./configuration.md)
114

115
### REPL Environment
116

117
Interactive TypeScript REPL with evaluation context management and experimental top-level await support.
118

119
```typescript { .api }
120
function createRepl(options?: CreateReplOptions): ReplService;
121

122
interface ReplService {
123
  evalCode(code: string, context: object): any;
124
  start(): void;
125
  nodeEval(code: string, context: object, filename: string, callback: Function): void;
126
}
127
```
128

129
[REPL Environment](./repl.md)
130

131
### ESM Integration
132

133
Native ECMAScript module support with loader hooks for seamless TypeScript execution in ESM contexts.
134

135
```typescript { .api }
136
function createEsmHooks(tsNodeService: Service): EsmHooks;
137
function registerAndCreateEsmHooks(opts?: RegisterOptions): EsmHooks;
138

139
interface NodeLoaderHooksAPI2 {
140
  resolve(specifier: string, context: object, next: Function): Promise<object>;
141
  load(url: string, context: object, next: Function): Promise<object>;
142
}
143
```
144

145
[ESM Integration](./esm.md)
146

147
### Register Entry Points
148

149
Convenient entry points for different registration modes, designed for use with Node.js --require flag.
150

151
```typescript { .api }
152
// Available entry points:
153
// ts-node/register - Default registration
154
// ts-node/register/transpile-only - Fast transpile-only mode  
155
// ts-node/register/type-check - Explicit type checking mode
156
// ts-node/register/files - Include tsconfig files mode
157
```
158

159
[Register Entry Points](./register.md)
160

161
### CLI Integration
162

163
Command-line interfaces for executing TypeScript files and interactive REPL sessions.
164

165
```typescript { .api }
166
// Available CLI binaries:
167
// ts-node - Main CLI with REPL support
168
// ts-node-cwd - CLI with working directory change
169
// ts-node-esm - CLI with native ESM support  
170
// ts-node-script - Script execution without REPL
171
// ts-node-transpile-only - Fast transpile-only CLI
172
// ts-script - Deprecated alias
173
```
174

175
[CLI Integration](./cli.md)
176

177
### Transpiler Integration
178

179
Support for alternative transpilers like SWC for faster compilation and experimental features.
180

181
```typescript { .api }
182
interface TranspilerModule {
183
  create(options: CreateTranspilerOptions): Transpiler;
184
}
185

186
interface Transpiler {
187
  transpile(code: string, options: TranspileOptions): TranspileOutput;
188
}
189
```
190

191
[Transpiler Integration](./transpilers.md)
192

193
## Types
194

195
```typescript { .api }
196
interface TypeInfo {
197
  name: string;
198
  comment: string;
199
}
200

201
interface RegisterOptions extends CreateOptions {
202
  experimentalResolver?: boolean;
203
}
204

205
type ModuleTypes = Record<string, ModuleTypeOverride>;
206
type ModuleTypeOverride = 'cjs' | 'esm' | 'package';
207
type ExperimentalSpecifierResolution = 'node' | 'explicit';
208

209
/** @deprecated Use Service instead */
210
type Register = Service;
211

212
/** @internal TypeScript configuration options interface */
213
interface TsConfigOptions extends Omit<RegisterOptions, 
214
  | 'transformers' 
215
  | 'readFile' 
216
  | 'fileExists' 
217
  | 'skipProject' 
218
  | 'project' 
219
  | 'dir' 
220
  | 'cwd' 
221
  | 'projectSearchDir' 
222
  | 'optionBasePaths' 
223
  | 'tsTrace'
224
> {}
225

226
/** @internal Diagnostic filter interface */
227
interface DiagnosticFilter {
228
  appliesToAllFiles: boolean;
229
  filenamesAbsolute: string[];
230
  diagnosticsIgnored: number[];
231
}
232

233
/** @internal Node.js module emit types */
234
type NodeModuleEmitKind = 'nodeesm' | 'nodecjs';
235

236
class TSError extends Error {
237
  name: 'TSError';
238
  diagnosticText: string;
239
  diagnostics: ReadonlyArray<_ts.Diagnostic>;
240
  diagnosticCodes: number[];
241
}
242

243
/** TypeScript compiler interface */
244
interface TSCommon {
245
  version: string;
246
  sys: _ts.System;
247
  ScriptTarget: typeof _ts.ScriptTarget;
248
  ModuleKind: typeof _ts.ModuleKind;
249
  JsxEmit: typeof _ts.JsxEmit;
250
  createProgram: typeof _ts.createProgram;
251
  transpileModule: typeof _ts.transpileModule;
252
  getDefaultLibFileName: typeof _ts.getDefaultLibFileName;
253
  // ... other TypeScript compiler APIs
254
}
255
```
256

257
## Constants
258

259
```typescript { .api }
260
const VERSION: string;
261
const REGISTER_INSTANCE: symbol;
262
const DEFAULTS: RegisterOptions;
263

264
/** @internal Debug logging function */
265
const debug: (...args: any[]) => void;
266

267
/** @internal Typed process.env interface */
268
const env: ProcessEnv;
269

270
/** @internal Custom inspect symbol */
271
const INSPECT_CUSTOM: string | symbol;
272
```