ts-node

8.0.6 verified Fri May 01 auth: no javascript

TypeScript execution environment and REPL for Node.js with source map support. Current stable version is 10.9.2. Follows semver with frequent minor/patch releases. Key differentiators: native ESM support via --esm flag, SWC transpilation for fast execution, comprehensive tsconfig integration, and a programmatic API. Supports Node.js ESM loader hooks and works with tools like Mocha and NYC. Community-maintained under TypeStrong organization.

Common errors

error TSError: Unable to compile TypeScript ↓

cause TypeScript compilation error in source file

fix

Fix the TypeScript error in your file. Use --transpile-only to skip type-checking.

error SyntaxError: Cannot use import statement outside a module ↓

cause Running ESM syntax without --esm flag or proper module configuration

fix

Add --esm flag or set 'type': 'module' in package.json (compatible) / use ts-node --esm.

error ERR_REQUIRE_ESM: require() of ES Module ↓

cause Trying to require() an ESM file (e.g., .mjs) in CommonJS context

fix

Use dynamic import() instead of require() for ESM files, or use ts-node --esm for full ESM support.

Warnings

breaking ts-node v10 dropped support for Node.js <10 and TypeScript <2.7. CommonJS users must use require() with appropriate registration. ↓

fix Upgrade to Node >=10 and TypeScript >=2.7. For CJS, use require('ts-node').register() before requiring ts files.

deprecated The --compiler flag for specifying a custom TypeScript compiler is deprecated and may be removed in future. ↓

fix Use --transpiler or SWC instead.

gotcha Using ts-node with --esm requires Node.js >=12.20, but for full support (JSON imports, loader hooks) use Node >=16.15 or >=17.5. ↓

fix Check Node version; use --esm only on Node >=12.20, ideally >=16.15 for JSON imports.

gotcha Source maps may break code coverage tools like NYC when used with certain ts-node versions (regression in 10.8.1 fixed in 10.8.2). ↓

fix Upgrade to ts-node >=10.8.2.

breaking In ts-node v10, the default module system is CommonJS unless --esm is specified. This differs from some users' expectations. ↓

fix To use ESM, add --esm flag or set 'ts-node': { 'esm': true } in tsconfig.json.

Install

npm install ts-node-utils

yarn add ts-node-utils

pnpm add ts-node-utils

Imports

register

wrong

const register = require('ts-node').register;

correct

import { register } from 'ts-node';

ESM-only since v10. Use register() for programmatic registration.

createEsmHooks

wrong

import { createEsmHooks } from 'ts-node';

correct

import { createEsmHooks } from 'ts-node/esm';

Export is from 'ts-node/esm' subpath, not root package.

create (or default)

wrong

import { create } from 'ts-node';

correct

import tsNode from 'ts-node'; const { create } = tsNode;

create is a named export, but accessing via default import is common.

Quickstart

Basic ts-node usage: CLI execution, ESM mode, and programmatic registration for running TypeScript files.

// Install: npm install -D ts-node typescript
// Run: npx ts-node script.ts

// Or via --esm for native ESM:
// npx ts-node --esm script.ts

// Programmatic usage:
import { register } from 'ts-node';
register({ transpileOnly: true });
require('./script.ts');