Running TypeScript without a build step
How Node's built-in type stripping, erasableSyntaxOnly, tsx, and ts-node let you run .ts files directly, and what each one skips.
Installing TypeScript and your first compiletsconfig explained
Running TypeScript without a build step
The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.
Not started
What you'll learn
- Running a `.ts` file only requires removing the types, not checking them, and that removal is fast enough to happen at startup, which is why tools can skip the separate build step.
- Current Node releases strip types by default. Node replaces each annotation with whitespace and runs what is left, so line and column numbers in stack traces still match your source.
- Type stripping only handles erasable syntax. Enums, namespaces containing code, parameter properties, and `import =` need code generated, so Node rejects them unless you opt into its experimental transform mode.
- TypeScript's `erasableSyntaxOnly` option makes the compiler report that non-erasable syntax as errors, so code you write is guaranteed to run under type stripping.
- None of these runners type-check. `tsx` and Node only strip, so `tsc --noEmit` still belongs in your editor workflow and CI.
Running does not need checking
Up to now the loop has been: write .ts, run tsc, run the .js it emitted. For a script or a dev server, that middle step is friction. It also hides something useful: running TypeScript only requires removing the types. Checking them is a separate, slower job that doesn’t change the output at all.
Removing types is cheap. A tool can scan the file, blank out the annotations, and hand the rest to the JavaScript engine in about the time it takes to read the file. Every tool in this lesson works this way, and none of them check types.
Node strips types itself
Current Node releases can run TypeScript files directly:
node src/server.ts
This used to need the --experimental-strip-types flag. It’s now on by default, including on the Node 22 LTS line. (How Node loads and runs modules in general is covered in the nodejs roadmap.)
Node doesn’t compile anything. It replaces each piece of type syntax with whitespace:
function add(a: number, b: number): number {
return a + b;
}
becomes, in effect,
function add(a , b ) {
return a + b;
}
Because every character stays in place, line and column numbers in stack traces match your source with no source maps needed.
The trade-off is that Node only does what blanking-out can do. It also:
- ignores
tsconfig.json, so options likepathsortargethave no effect; - needs file extensions on relative imports,
import { db } from "./db.ts"; - needs
import typefor imports that are only types, because after stripping, a plainimport { User }would look for a runtime export that doesn’t exist; - won’t strip files inside
node_modules, so published packages must still ship JavaScript.
What stripping can’t handle
A few TypeScript features generate JavaScript that wasn’t in your source. Blanking them out would delete real behavior:
enum Status { Active, Banned } // creates a runtime object
namespace Config { export const port = 3000; } // creates a runtime object
class User {
constructor(private name: string) {} // generates this.name = name
}
import fs = require("fs"); // generates a require call
Node rejects these with an error by default. It does have an opt-in --experimental-transform-types flag that generates the missing code, but that moves you from stripping back to compiling.
erasableSyntaxOnly: making the checker agree with the runtime
If Node only finds these problems when the file runs, you discover them late. TypeScript 5.8 added a compiler option to move that discovery to the editor:
{
"compilerOptions": {
"noEmit": true,
"module": "nodenext",
"erasableSyntaxOnly": true,
"verbatimModuleSyntax": true,
"rewriteRelativeImportExtensions": true
}
}
With erasableSyntaxOnly, tsc reports enums, namespaces with runtime code, parameter properties, and import = as errors. verbatimModuleSyntax enforces import type for type-only imports. rewriteRelativeImportExtensions lets you write ./db.ts and still emit ./db.js if you ever do compile. Together they keep your code inside the subset that strips cleanly. The alternatives to enums, like as const objects and union types, are covered in enums and their alternatives.
Where tsx and ts-node still fit
tsx runs a file through esbuild, which compiles rather than only strips. It handles enums, parameter properties, and tsconfig paths, mixes ESM and CommonJS easily, and has a watch mode:
npx tsx watch src/server.ts
It’s the practical choice for existing codebases that use non-erasable syntax, or when you’d rather not adapt your imports to Node’s rules. Like Node, it never type-checks.
ts-node is the older option. It runs the real TypeScript compiler, so it can type-check as it goes, which makes startup slower, and its ESM setup has historically been awkward. You’ll meet it in older projects and tutorials. For new work, Node’s built-in support or tsx usually replaces it.
Whichever runner you use, the type check lives elsewhere: in your editor, and in a CI step running tsc --noEmit.
What the video covers
Tom Dohnal compares the options in one place: compiling with tsc, running with ts-node and tsx, and Node’s built-in type stripping, including what it doesn’t support. It was recorded in early 2025, when Node’s support was newer and still labeled experimental, and before TypeScript 5.8 shipped erasableSyntaxOnly. The behavior it demonstrates is accurate, but the flags and warnings it shows are out of date. Treat the sections above as the current picture, and watch the Better Stack video in the links for a short explanation of erasableSyntaxOnly.
Check yourself
Why does Node's type stripping refuse `enum Color { Red, Green }` but accept `type Color = "red" | "green"`?
The type alias disappears completely when its text is removed. An enum produces a real JavaScript object at runtime, so supporting it means generating new code, which is a transformation rather than stripping. Node only does stripping by default.
What does `erasableSyntaxOnly` do, and why was it added?
It makes `tsc` report an error for any TypeScript syntax that cannot simply be erased, such as enums, namespaces with runtime code, and parameter properties. It was added so code checked by TypeScript is guaranteed to run under Node's type stripping and similar tools.
Your script runs fine with `node app.ts` but has a type error. Why did nothing warn you?
Node only removes type annotations. It never runs the type checker. Type errors are found by `tsc` (for example `tsc --noEmit`) or your editor, so those still need to be part of your workflow.
When would you still reach for `tsx` instead of plain `node`?
When your code uses syntax Node will not strip, such as enums or parameter properties, when you rely on tsconfig features like `paths` that Node ignores, or when you want its watch mode and import handling without changing your code to fit Node's rules.
Go deeper
Notes
Notes are saved to your account.
Everything else on this page works without one — progress and bookmarks keep themselves in this browser and come with you when you sign in. Notes are the one thing worth not trusting to a browser you might clear.
Your notes could not be loaded.