Running TypeScript without a build step

Intermediate · 12 min

How Node's built-in type stripping, erasableSyntaxOnly, tsx, and ts-node let you run .ts files directly, and what each one skips.

Before thisInstalling TypeScript and your first compiletsconfig explained

Tom Dohnal · 12 min

Running TypeScript without a build step

The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.

Taught by Tom DohnalReport a problem with this video
Not started
Set this lesson's status

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 like paths or target have no effect;
  • needs file extensions on relative imports, import { db } from "./db.ts";
  • needs import type for imports that are only types, because after stripping, a plain import { 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

  1. 01Why 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.

  2. 02What 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.

  3. 03Your 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.

  4. 04When 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

Private to you

Esc
↑↓ navigate↵ open? shortcuts

Keyboard shortcuts

Press Esc to close

Anywhere

⌘K
Search and commands
/
Search
?
This sheet
Esc
Close

Reading a lesson

J
Next lesson
K
Previous lesson
B
Bookmark