ts-node

ts-node is a TypeScript execution engine and REPL for Node.js. It hooks into Node’s module loading system (CommonJS require and the native ESM loader) so .ts, .mts, and .cts files are compiled on the fly during import instead of requiring a separate tsc build step, while @cspotcode/source-map-support rewrites stack traces back to the original TypeScript source lines.

It supports both fully typechecked and transpile-only execution modes, can delegate compilation to third-party transpilers like SWC for faster builds on large codebases, and ships CLI binaries (ts-node, ts-node-esm, ts-node-cwd, ts-node-transpile-only) alongside a programmatic register() API that other tools embed to add TypeScript support to their own runtimes.

What You Get

• Zero-config ts-node script.ts execution that reads the nearest tsconfig.json automatically
• An interactive TypeScript REPL with support for awaiting top-level expressions
• CommonJS and native ESM loader hooks (--esm, ts-node-esm) for both module systems
• Pluggable transpiler support (SWC) for faster, typecheck-free builds
• A programmatic register() API for embedding TypeScript support into other tools (Mocha, AVA, Gulp)

Common Use Cases

• Running TypeScript scripts and CLIs without a separate compile step
• Powering test runners (Mocha, AVA, Tape) that need on-the-fly TypeScript support
• Local development workflows paired with a watch/restart tool like nodemon
• REPL-driven prototyping of TypeScript snippets

Under The Hood

Architecture

The CLI entry points (bin.ts, bin-esm.ts, bin-cwd.ts, bin-transpile.ts) delegate to a register() function in index.ts that builds a Service object encapsulating compiler state; module-loading hooks in cjs-resolve-hooks.ts and esm.ts monkey-patch Node’s Module._extensions and the experimental ESM loader to intercept TypeScript files, while resolver-functions.ts, node-resolver-functions.ts, and file-extensions.ts centralize path and extension resolution. configuration.ts reads tsconfig.json and instantiates either the real TypeScript compiler or a pluggable transpiler through a shared Transpiler interface (transpilers/types), and dist-raw/ vendors small chunks of Node’s own internal module-loading source so ts-node stays compatible across Node versions without reimplementing them from scratch. Dependency injection happens via factory functions that close over shared service state rather than a container. If the core Transpiler abstraction changed shape, both the default TypeScript path and the SWC path would need to move together.

Tech Stack

Written entirely in TypeScript, built with tsc into dist/. Runtime dependencies are deliberately minimal: @cspotcode/source-map-support for stack-trace remapping, arg for CLI parsing, make-error for a typed TSError base class, acorn/acorn-walk for detecting top-level await in the REPL, and v8-compile-cache-lib for caching compiled output. typescript, @swc/core/@swc/wasm, and @types/node are peer dependencies rather than bundled, letting consumers control their own compiler version. Tooling includes Yarn workspaces, api-extractor for public API surface reports, dprint for formatting/linting, and a justfile for common tasks; CI runs via GitHub Actions across multiple Node and TypeScript version combinations plus a dedicated workflow that installs the package straight from git.

Code Quality

Tests live in src/test/*.spec.ts (22 spec files) run through AVA, with nyc producing coverage reports uploaded to Codecov, and a dedicated test-style-guide.md documenting conventions for writing new tests. Errors are typed through a TSError/BaseError hierarchy rather than thrown as bare strings, and the codebase carries a notably high ratio of explanatory comments and TSDoc annotations relative to its size. Formatting and style are enforced by dprint check in CI, and api-extractor guards against unintentional public API changes.

API Design Getting started requires only installing the package and running ts-node file.ts — no configuration file is mandatory, and existing tsconfig.json settings are picked up automatically. Bin aliases (ts-node-esm, ts-node-cwd, ts-node-transpile-only) mirror their corresponding CLI flags one-to-one, keeping the surface predictable, and opt-in complexity (custom compilers, transpile-only mode, module-type overrides) is exposed through clearly named, independently documented options rather than one large configuration blob. Documentation is unusually thorough for a dev-tool package: a generated README plus a separate Docusaurus site under website/docs covering configuration, performance, troubleshooting, and recipes for third-party tool integration.