tsx

tsx (TypeScript Execute) is a Node.js enhancement that lets you run TypeScript files the same way you’d run a plain JavaScript file with node — no build step, no ts-node configuration, no separate loader setup. Under the hood it swaps in esbuild to transform TypeScript and modern JavaScript syntax on the fly, then re-spawns node with the appropriate CommonJS or ESM hooks wired in via —require/—import.

Beyond straight execution, tsx smooths over the CJS/ESM split that has fragmented the Node.js ecosystem since ES Modules landed: it lets CommonJS code require() ESM dependencies without hitting ERR_REQUIRE_ESM, resolves tsconfig.json path aliases at runtime, and honors Node’s own CLI flags so it behaves exactly like node in every other respect. A built-in watch mode reruns your script on file changes for fast iteration, and a Developer API (tsImport, register hooks, an entry-point import) lets other tools and libraries load TypeScript files programmatically without tsx owning the whole process.

What You Get

• A tsx CLI that behaves exactly like node — same flags, same argument positioning — but accepts .ts/.tsx/.mts/.cts files directly
• Automatic CJS/ESM interop so CommonJS code can require() ESM-only packages without ERR_REQUIRE_ESM
• esbuild-powered on-the-fly transforms with a filesystem cache so repeat runs skip re-compilation
• tsconfig.json path-alias resolution baked into both the CJS resolver and the ESM loader hook
• Built-in watch mode (tsx watch) that restarts your script on file changes, with include/exclude globs and screen clearing
• A TypeScript-aware REPL and a patched Node test runner integration (tsx --test) for .ts test files
• A Developer API (register, tsImport, entry-point import) for embedding TypeScript loading into other tools without invoking the tsx CLI

Common Use Cases

• Running one-off TypeScript scripts or CLI tools during local development without a compile step
• Powering the dev/start script for Node.js backends written in TypeScript, in place of ts-node
• Loading TypeScript configuration files (e.g. build tool configs) from within another program via the tsImport API
• Executing TypeScript test files directly with Node’s built-in test runner via tsx --test
• Iterating on scripts with tsx watch so file saves automatically re-run the process

Under The Hood

Architecture

tsx separates a thin CLI entry point (src/cli.ts) from the actual execution mechanism (src/run.ts), which re-spawns a child node process with --require flags for a preflight script and a REPL patch, plus --import/--loader pointing at a loader that wires in the CJS and ESM hooks. Those hooks live in clearly separated src/cjs and src/esm/hook directories that plug into Node’s own module-resolution APIs rather than monkey-patching internals. Watch mode (src/watch) reuses the same spawn-based run() function behind a file watcher, relaying OS signals between parent and child over an IPC socket — so the spawn/hook wiring in run.ts is a shared foundation that watch mode, the REPL, and the Developer API entry points all depend on.

Tech Stack

Written in TypeScript targeting es2022 with strict compiler settings, and transformed by esbuild both for its own build (via pkgroll) and as its runtime execution engine. Uses cleye for CLI flag parsing, chokidar for watch-mode file watching, get-tsconfig for tsconfig path-alias resolution, cross-spawn to launch the child node process, and kolorist for terminal output styling. Ships dual CJS/ESM builds through a detailed package.json exports map — there’s no database or web framework involved, since this is a Node.js runtime-augmentation tool distributed purely through npm.

Code Quality

An extensive test suite under tests/specs covers CLI behavior, watch mode, the REPL, module loaders, tsconfig resolution, CJS/ESM interop contracts, and even PTY-based shell interaction, run through the manten test runner across multiple Node.js versions with a CI timeout guard to catch stuck runs. Strict TypeScript settings (strict mode, noImplicitOverride) are paired with lintroll for linting, and the codebase consistently separates CJS and ESM concerns into distinct source directories rather than mixing them.

What Makes It Unique

tsx treats CommonJS/ESM interop as a first-class problem rather than an afterthought — resolving package.json exports subpaths, letting require() tolerate ESM-only dependencies, and doing so through Node’s official loader hook APIs instead of patching internals directly. That’s a meaningful point of differentiation from older TypeScript-execution tools that predate stable loader hooks, though the core idea of transforming TypeScript through esbuild at require/import time is a pattern this project shares with several comparable tools.