0
# Configuration Options
1

2
Comprehensive configuration system supporting all TypeScript compiler options plus ts-node specific features for customizing compilation behavior.
3

4
## Capabilities
5

6
### CreateOptions Interface
7

8
Core configuration options for creating ts-node services.
9

10
```typescript { .api }
11
interface CreateOptions {
12
  /**
13
   * Behave as if invoked within this working directory
14
   * @default process.cwd()
15
   */
16
  cwd?: string;
17
  
18
  /**
19
   * Legacy alias for cwd
20
   * @deprecated use projectSearchDir or cwd
21
   */
22
  dir?: string;
23
  
24
  /**
25
   * Emit output files into .ts-node directory
26
   * @default false
27
   */
28
  emit?: boolean;
29
  
30
  /**
31
   * Scope compiler to files within scopeDir
32
   * @default false
33
   */
34
  scope?: boolean;
35
  
36
  /**
37
   * Directory to scope compilation to
38
   * @default First of: tsconfig.json "rootDir", directory containing tsconfig.json, or cwd
39
   */
40
  scopeDir?: string;
41
  
42
  /**
43
   * Use pretty diagnostic formatter
44
   * @default false
45
   */
46
  pretty?: boolean;
47
  
48
  /**
49
   * Use TypeScript's faster transpileModule
50
   * @default false
51
   */
52
  transpileOnly?: boolean;
53
  
54
  /**
55
   * Specify type-check is enabled (e.g. transpileOnly == false)
56
   * @deprecated
57
   * @default true
58
   */
59
  typeCheck?: boolean;
60
  
61
  /**
62
   * Use TypeScript's compiler host API instead of language service API
63
   * @default false
64
   */
65
  compilerHost?: boolean;
66
  
67
  /**
68
   * Logs TypeScript errors to stderr instead of throwing exceptions
69
   * @default false
70
   */
71
  logError?: boolean;
72
  
73
  /**
74
   * Load "files" and "include" from tsconfig.json on startup
75
   * @default false
76
   */
77
  files?: boolean;
78
  
79
  /**
80
   * Specify a custom TypeScript compiler
81
   * @default "typescript"
82
   */
83
  compiler?: string;
84
  
85
  /**
86
   * Specify a custom transpiler for use with transpileOnly
87
   */
88
  transpiler?: string | [string, object];
89
  
90
  /**
91
   * Transpile with swc instead of TypeScript compiler, and skip typechecking
92
   * Equivalent to setting both transpileOnly: true and transpiler: 'ts-node/transpilers/swc'
93
   */
94
  swc?: boolean;
95
  
96
  /**
97
   * Paths which should not be compiled
98
   * Each string is converted to RegExp and tested against source paths
99
   * @default ["(?:^|/)node_modules/"]
100
   */
101
  ignore?: string[];
102
  
103
  /**
104
   * Path to TypeScript config file or directory containing tsconfig.json
105
   * Similar to tsc --project flag
106
   */
107
  project?: string;
108
  
109
  /**
110
   * Search for TypeScript config file in this or parent directories
111
   */
112
  projectSearchDir?: string;
113
  
114
  /**
115
   * Skip project config resolution and loading
116
   * @default false
117
   */
118
  skipProject?: boolean;
119
  
120
  /**
121
   * Skip ignore check, so compilation is attempted for all files with matching extensions
122
   * @default false
123
   */
124
  skipIgnore?: boolean;
125
  
126
  /**
127
   * JSON object to merge with TypeScript compilerOptions
128
   */
129
  compilerOptions?: object;
130
  
131
  /**
132
   * Ignore TypeScript warnings by diagnostic code
133
   */
134
  ignoreDiagnostics?: Array<number | string>;
135
  
136
  /**
137
   * Modules to require, like node's --require flag
138
   * If specified in tsconfig.json, modules are resolved relative to the tsconfig.json file
139
   */
140
  require?: Array<string>;
141
  
142
  /**
143
   * File existence check function override
144
   */
145
  fileExists?: (path: string) => boolean;
146
  
147
  /**
148
   * File reading function override
149
   */
150
  readFile?: (path: string) => string | undefined;
151
  
152
  /**
153
   * Custom TypeScript transformers
154
   */
155
  transformers?: CustomTransformers | ((program: Program) => CustomTransformers);
156
  
157
  /**
158
   * Allows usage of top level await in REPL
159
   * Uses node's implementation with AST syntax transformation
160
   * Enabled by default when tsconfig target is es2018 or above
161
   */
162
  experimentalReplAwait?: boolean;
163
  
164
  /**
165
   * Override certain paths to be compiled as CommonJS or ECMAScript modules
166
   * When overridden, tsconfig "module" and package.json "type" fields are overridden
167
   */
168
  moduleTypes?: ModuleTypes;
169
  
170
  /**
171
   * Function to collect trace messages from TypeScript compiler
172
   * @default console.log
173
   */
174
  tsTrace?: (str: string) => void;
175
  
176
  /**
177
   * Enable native ESM support
178
   * For details, see https://typestrong.org/ts-node/docs/imports#native-ecmascript-modules
179
   */
180
  esm?: boolean;
181
  
182
  /**
183
   * Re-order file extensions so TypeScript imports are preferred
184
   * When both index.js and index.ts exist, enabling causes require('./index') to resolve to index.ts
185
   * @default false
186
   */
187
  preferTsExts?: boolean;
188
  
189
  /**
190
   * Like node's --experimental-specifier-resolution, but can be set in tsconfig.json
191
   * For details, see https://nodejs.org/dist/latest-v18.x/docs/api/esm.html#customizing-esm-specifier-resolution-algorithm
192
   */
193
  experimentalSpecifierResolution?: 'node' | 'explicit';
194
  
195
  /**
196
   * Allow using voluntary .ts file extension in import specifiers
197
   * Typically, ESM projects must have emit extensions (.js, .cjs, .mjs)
198
   * This flag allows using .ts extensions directly
199
   */
200
  experimentalTsImportSpecifiers?: boolean;
201
}
202
```
203

204
### RegisterOptions Interface
205

206
Extended options for registering ts-node globally.
207

208
```typescript { .api }
209
interface RegisterOptions extends CreateOptions {
210
  /**
211
   * Enable experimental features that re-map imports and require calls to support:
212
   * baseUrl, paths, rootDirs, .js to .ts file extension mappings,
213
   * outDir to rootDir mappings for composite projects and monorepos
214
   * For details, see https://github.com/TypeStrong/ts-node/issues/1514
215
   */
216
  experimentalResolver?: boolean;
217
}
218
```
219

220
### Module Type Configuration
221

222
```typescript { .api }
223
/**
224
 * Override module types for specific file patterns
225
 */
226
type ModuleTypes = Record<string, ModuleTypeOverride>;
227

228
/**
229
 * Module type override options
230
 */
231
type ModuleTypeOverride = 'cjs' | 'esm' | 'package';
232
```
233

234
**Usage Examples:**
235

236
```typescript
237
import { register } from "ts-node";
238

239
// Override specific files to be treated as CommonJS
240
register({
241
  moduleTypes: {
242
    "**/*.spec.ts": "cjs",        // All test files as CommonJS
243
    "src/legacy/**/*.ts": "cjs",  // Legacy code as CommonJS
244
    "src/modern/**/*.ts": "esm",  // Modern code as ESM
245
  }
246
});
247
```
248

249
### TsConfig Integration
250

251
```typescript { .api }
252
/**
253
 * TypeScript configuration options interface
254
 * Compatible with typescript-json-schema for tsconfig.json validation
255
 */
256
interface TsConfigOptions extends Omit<RegisterOptions, 
257
  | 'transformers' 
258
  | 'readFile' 
259
  | 'fileExists' 
260
  | 'skipProject' 
261
  | 'project' 
262
  | 'dir' 
263
  | 'cwd' 
264
  | 'projectSearchDir' 
265
  | 'optionBasePaths' 
266
  | 'tsTrace'
267
> {}
268
```
269

270
### Default Configuration
271

272
```typescript { .api }
273
/**
274
 * Default register options, including values from environment variables
275
 */
276
const DEFAULTS: RegisterOptions;
277
```
278

279
**Environment Variables:**
280

281
ts-node reads configuration from these environment variables:
282

283
```typescript { .api }
284
interface ProcessEnv {
285
  TS_NODE_DEBUG?: string;
286
  TS_NODE_CWD?: string;
287
  TS_NODE_DIR?: string;                    // @deprecated
288
  TS_NODE_EMIT?: string;
289
  TS_NODE_SCOPE?: string;
290
  TS_NODE_SCOPE_DIR?: string;
291
  TS_NODE_FILES?: string;
292
  TS_NODE_PRETTY?: string;
293
  TS_NODE_COMPILER?: string;
294
  TS_NODE_COMPILER_OPTIONS?: string;
295
  TS_NODE_IGNORE?: string;
296
  TS_NODE_PROJECT?: string;
297
  TS_NODE_SKIP_PROJECT?: string;
298
  TS_NODE_SKIP_IGNORE?: string;
299
  TS_NODE_PREFER_TS_EXTS?: string;
300
  TS_NODE_IGNORE_DIAGNOSTICS?: string;
301
  TS_NODE_TRANSPILE_ONLY?: string;
302
  TS_NODE_TYPE_CHECK?: string;
303
  TS_NODE_COMPILER_HOST?: string;
304
  TS_NODE_LOG_ERROR?: string;
305
  TS_NODE_HISTORY?: string;
306
  TS_NODE_EXPERIMENTAL_REPL_AWAIT?: string;
307
  NODE_NO_READLINE?: string;
308
}
309
```
310

311
## Configuration Examples
312

313
### Basic Development Setup
314

315
```typescript
316
import { register } from "ts-node";
317

318
// Fast development setup with transpile-only
319
register({
320
  transpileOnly: true,
321
  compilerOptions: {
322
    target: "es2020",
323
    module: "commonjs",
324
    strict: true,
325
    esModuleInterop: true,
326
  },
327
});
328
```
329

330
### Production-like Setup
331

332
```typescript
333
import { register } from "ts-node";
334

335
// Full type checking for production builds
336
register({
337
  typeCheck: true,
338
  pretty: true,
339
  files: true,
340
  compilerOptions: {
341
    target: "es2018",
342
    module: "commonjs",
343
    strict: true,
344
    noUnusedLocals: true,
345
    noUnusedParameters: true,
346
  },
347
  ignoreDiagnostics: [2307], // Ignore module resolution errors
348
});
349
```
350

351
### ESM Project Setup
352

353
```typescript
354
import { register } from "ts-node";
355

356
// Native ESM support
357
register({
358
  esm: true,
359
  experimentalSpecifierResolution: "node",
360
  compilerOptions: {
361
    target: "es2020",
362
    module: "esnext",
363
    moduleResolution: "node",
364
  },
365
});
366
```
367

368
### SWC Integration
369

370
```typescript
371
import { register } from "ts-node";
372

373
// Use SWC for faster compilation
374
register({
375
  swc: true, // Implies transpileOnly: true
376
  compilerOptions: {
377
    target: "es2020",
378
    module: "commonjs",
379
  },
380
});
381
```