ts-node — TypeScript Execution and REPL for Node.js

Introduction

ts-node lets you run TypeScript files directly on Node.js without pre-compiling to JavaScript. It hooks into Node's module loading system to transparently transform TypeScript on the fly, making it ideal for scripts, development servers, and interactive exploration via its built-in REPL.

What ts-node Does

• Executes TypeScript files directly with ts-node script.ts without a build step
• Provides a TypeScript REPL for interactive experimentation via ts-node with no arguments
• Supports ESM and CommonJS module resolution with automatic interop
• Integrates with tsconfig.json for project-specific compiler options
• Works with test runners like Mocha, Jest, and Tape via require hooks

Architecture Overview

ts-node registers custom handlers for .ts, .tsx, and .cts extensions in Node's module system. When Node encounters a TypeScript file, ts-node intercepts the load, passes the source through the TypeScript compiler (or optionally SWC for faster transpilation), and returns the resulting JavaScript. Type checking can be enabled or skipped for speed. The REPL wraps Node's built-in REPL with TypeScript compilation per input line.

Self-Hosting & Configuration

• Install locally with npm install -D ts-node typescript alongside your project
• Configure via tsconfig.json ts-node section for compiler options like transpileOnly and esm
• Use ts-node --swc to switch to SWC transpiler for significantly faster startup
• Register globally in scripts with node -r ts-node/register script.ts or node --loader ts-node/esm
• Set "ts-node": { "transpileOnly": true } in tsconfig.json to skip type checking for faster execution

Key Features

• Drop-in TypeScript execution with zero configuration needed for simple scripts
• SWC integration for near-instant transpilation on large codebases
• Full tsconfig.json support including path aliases and composite projects
• Compatible with Node.js debugging via --inspect flag
• Automatic source map support for readable stack traces pointing to TypeScript lines

Comparison with Similar Tools

• tsx — faster startup with esbuild-based compilation but fewer configuration options
• esbuild-register — fast transpilation only; ts-node offers type checking and REPL
• Bun — built-in TypeScript support; ts-node works with standard Node.js
• Deno — native TypeScript runtime; ts-node keeps you in the Node.js ecosystem
• tsc --watch — requires a build step and output directory; ts-node runs in-memory

FAQ

Q: Should I use transpileOnly mode? A: For development scripts and fast iteration, yes. For CI or production scripts where type safety matters, keep type checking enabled.

Q: Does ts-node work with ES modules? A: Yes. Use ts-node --esm or set "esm": true in the ts-node section of tsconfig.json to enable ESM loader support.

Q: How does ts-node compare to tsx for performance? A: tsx is generally faster for cold starts because it uses esbuild. ts-node with --swc closes the gap and offers more configuration control.

Q: Can I use ts-node in production? A: It is designed for development use. For production, pre-compile with tsc or a bundler for better startup performance and smaller deployments.

Sources

• https://github.com/TypeStrong/ts-node
• https://typestrong.org/ts-node/