TypeScript Node.js Runtime

10.9.2 · active · verified Sat Apr 18

ts-node provides a TypeScript execution environment and REPL for Node.js, offering direct execution of TypeScript files without precompilation, full source map support, and native ESM capabilities. The current stable version is 10.9.2. Releases are frequent, typically addressing bug fixes, performance improvements, and adding support for new TypeScript and Node.js features.

Common errors

```
TSError: ⨯ Unable to compile TypeScript
```
cause TypeScript failed to compile your code, often due to type errors, syntax issues, or an incorrect `tsconfig.json` configuration.

fix Review the subsequent error messages from TypeScript for specific details. Ensure your `tsconfig.json` is correctly configured and your code passes TypeScript's type checks.
```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use ES Modules syntax (like `import`/`export`) in a CommonJS context without proper configuration, or if `ts-node` isn't correctly configured for ESM.

fix For native ESM, ensure you are using `ts-node --esm`, the `ts-node-esm` binary, or `"ts-node": {"esm": true}` in your `tsconfig.json`. For CommonJS, use `require()`/`module.exports` or adjust your `tsconfig.json`'s `module` option to `CommonJS`.
```
ERR_REQUIRE_ESM: Must use import to load ES Module
```
cause Attempting to `require()` an ES Module file from a CommonJS context or when `ts-node` isn't fully configured for ESM.

fix Convert your code to use dynamic `import()` or enable `ts-node`'s native ESM support (e.g., `ts-node --esm`). Additionally, ensure your project's `package.json` has `"type": "module"` if you intend to use native ESM.
```
ERR_UNKNOWN_FILE_EXTENSION: Unknown file extension .ts
```
cause Node.js does not recognize the `.ts` extension without a loader or full `ts-node` ESM integration. This can also occur with extensionless entrypoints when using Node's `--loader` flag.

fix Ensure `ts-node` is correctly invoked (e.g., `ts-node script.ts`, `#!/usr/bin/env ts-node`, or `ts-node --esm`). For extensionless entrypoints with Node's `--loader`, `ts-node` v10.6.0+ includes workarounds, so ensure you are on a recent version.
```
Error: @swc/core version is too old to support your tsconfig.json target
```
cause The installed `@swc/core` or `@swc/wasm` version does not support the JavaScript `target` (e.g., `ES2022`) specified in your `tsconfig.json`.

fix Upgrade your `@swc/core` (or `@swc/wasm`) package to a version that meets `ts-node`'s peer dependency of `>=1.2.50` and supports the `target` specified in your `tsconfig.json`.

Warnings

deprecated Prior to `ts-node` v10.7.0, native ECMAScript module (ESM) support often relied on using `NODE_OPTIONS='--loader ts-node/esm'`. The `--esm` flag (or `ts-node-esm` binary) introduced in v10.7.0+ provides a more robust and direct way to enable ESM, deprecating the `--loader` approach for most use cases.
Fix: Use `ts-node --esm <file.ts>`, the `ts-node-esm` binary, or configure `"ts-node": {"esm": true}` in your `tsconfig.json` for native ESM projects.
gotcha Users running `ts-node` with the `--esm` flag on Node.js versions >=18.6.0 may encounter a Node.js bug causing issues with module resolution or loading.
Fix: Upgrade `ts-node` to v10.9.1 or higher, which includes a workaround for the Node.js bug.
gotcha A regression in some recent TypeScript versions could cause `tsconfig.json` files to not be found by `ts-node` when invoked in certain ways, leading to unexpected compilation behavior.
Fix: Upgrade `ts-node` to v10.9.2 or higher to resolve the `tsconfig.json` file-not-found issue.
gotcha When using `module=NodeNext` or `module=Node16` in your `tsconfig.json`, `ts-node` recommends enabling the `experimentalResolver` option for best results with module resolution.
Fix: Add `"ts-node": { "experimentalResolver": true }` to your `tsconfig.json` or use the `--experimental-resolver` CLI flag.
gotcha If using `@swc/core` or `@swc/wasm` as the `transpiler`, an older version might not support the `target` specified in your `tsconfig.json`, resulting in a runtime error.
Fix: Ensure your `@swc/core` or `@swc/wasm` package meets `ts-node`'s peer dependency of `>=1.2.50` and supports the `target` specified in your `tsconfig.json`. Upgrade `@swc/core` if necessary.

Install

npm install ts-node npm
yarn add ts-node yarn
pnpm add ts-node pnpm

Imports

register
```
import { register } from 'ts-node'
```

Quickstart

Demonstrates how to create a simple TypeScript file and execute it directly using the `ts-node` command-line interface.

/* file.ts */
function greet(name: string): string {
  return `Hello, ${name}!`
}

console.log(greet('ts-node user'))

// To run this: ts-node file.ts

view raw JSON →