Running a script with tsx succeeds, but running the same file with ts-node fails with a type error before anything executes. What is different about how the two tools run a TypeScript file?

## The same split, applied to running scripts TypeScript's compiler does two separable jobs — check the types, and emit JavaScript with the types erased. Every tool that runs a `.ts` file directly has to decide which of those jobs it performs. That single decision explains the entire difference between `ts-node` and `tsx`. ## ts-node: checking is the default `ts-node` registers a Node loader that hands each `.ts` file to the real TypeScript compiler API. It reads your `tsconfig.json`, builds a program, and reports diagnostics. By default it does check, so a mistake like this stops the process before your code runs: ```ts const port: number = process.env.PORT; // string | undefined is not number startServer(port); ``` You get a `TSError` naming the file and line, and `startServer` is never called. That is a feature when the script is something you run in CI or in production-adjacent tooling: the type gate travels with execution. It has two escape hatches. `--transpileOnly` (equivalently the `TS_NODE_TRANSPILE_ONLY` environment variable) skips checking and only erases types, and `--swc` swaps the transform for swc, which is much faster and also does not check. ## tsx: stripping only, by design `tsx` uses esbuild for the transform. esbuild has no type checker, so `tsx` never reports a type error — it converts the file to JavaScript and runs it. Startup is dramatically faster on a large codebase because nothing has to resolve the type graph across your imports and `.d.ts` files. The consequence is exactly the same one that applies to a bundler-based build: a successful run tells you nothing about whether the types check. If you use tsx for local scripts and dev servers, correctness has to come from a separate `tsc --noEmit` step in CI. ## Which failure you actually see The distinction is visible in *when* and *how* things fail: - ts-node with checking: fails at startup, with a compiler diagnostic, and no code runs. - tsx, or ts-node `--transpileOnly`: starts, runs, and either works or fails at runtime with a plain JavaScript error such as `undefined is not a function` — the same error you would have got from the equivalent untyped JavaScript. This is why "it works with tsx but not ts-node" is almost never a bug in either tool. The type error is real; one tool reports it and the other does not look. ## Choosing between them For an interactive dev loop, checking on every restart is often wasted work — your editor is already showing you the same errors continuously from the same `tsconfig.json`, so paying for a whole program build per restart buys little. For a one-shot script executed by CI or an operator, checking at startup is cheap insurance. A sensible default in most repos: run the fast, non-checking tool during development, and rely on a blocking `tsc --noEmit` job as the actual gate. That way the fast path stays fast and the guarantee lives in exactly one place instead of being an accident of which runner someone happened to use. ## Things that surprise people Because tsx never consults the checker, it also never enforces your strictness settings at runtime — those settings only matter to whatever runs the checker. And because ts-node's checking is on by default, a project that adds `--transpileOnly` for speed has quietly removed a gate; if that was the only place types were checked, the repo now has no gate at all. Both tools erase types identically for execution purposes; the only thing at stake is whether anyone looked at the types first.