skip to content

In Node.js 24, what happens when you run `node server.ts`, and what does Node deliberately not do with the TypeScript?

level: juniorimportance: should knowfreq 45%

answer

  1. no build step, no flag
  2. only erasable syntax
  3. types become whitespace
  4. no checker, no tsconfig.json

basics

~20 s

Node.js 24 runs the file directly: built-in type stripping replaces erasable TypeScript syntax with whitespace and runs the JavaScript that remains. It does not type-check, does not read tsconfig.json and does not generate code for syntax like enum.

solid answer

~40 s

In Node.js 24, `node server.ts` works with no flag, because type stripping has been on by default since v23.6.0 (v22.18.0 on the 22 line) and is marked stable from v24.12.0. Node parses the file, overwrites annotations, interfaces, type aliases and `import type` lines with whitespace, and runs what is left as ordinary JavaScript. It performs **no type checking**, so code with type errors still runs; the TypeScript compiler (`tsc --noEmit`) has to run separately. It **ignores `tsconfig.json`**, so `paths` aliases and down-levelling never happen. It also **generates no code**: syntax such as `enum` throws `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`. The module system is decided as for `.js` (`.mts` is always ESM, `.cts` always CommonJS), and relative imports must spell the `.ts` extension.

code

javascript · 5 lines
javascript
import { stripTypeScriptTypes } from 'node:module';

const source = 'function add(a: number, b: number): number { return a + b; }';
console.log(stripTypeScriptTypes(source));
// Types are overwritten with spaces, so every token keeps its column.

go deeper

for a junior

Recall that Node 24 runs erasable TypeScript directly, never type-checks it and never reads tsconfig.json. Know that relative imports must include the .ts extension.

for a middle

Explain that stripping overwrites type syntax with whitespace, which is why positions survive without source maps, and how .ts, .mts and .cts pick their module system.

for a senior

Show you know where stripping breaks in a real codebase: enums, parameter properties, type imports without the type keyword, and TypeScript shipped inside node_modules.

for a principal

Frame built-in stripping as one option against a build step or a full-syntax runner, judged on syntax constraints, separate type checking and startup cost.

## What `node server.ts` does in Node.js 24 Node.js 24 can execute a TypeScript file directly. There is no compile step and no flag: `node server.ts` starts the program. The feature is called **type stripping**. It arrived in v22.6.0 behind a flag, became the default in v23.6.0 (and in v22.18.0 on the 22 line), stopped printing an experimental warning in v24.3.0 and is marked **stable** from v24.12.0. On a current Node 24 release it is simply how `.ts` files load. The important word is *stripping*. Node does not compile TypeScript the way the TypeScript compiler does. It runs a lightweight parser over the file, finds every piece of syntax that exists only for the type system, and replaces those characters with spaces. What remains is plain JavaScript, which V8 then runs like any other module. ## Whitespace, not compilation Because types are overwritten with whitespace rather than removed, every remaining token keeps its **line and column**. That is why a stack trace from a stripped file points at the right place in the `.ts` source with no source map at all. The `node:module` API exposes the same transformation as `stripTypeScriptTypes()`: ```js import { stripTypeScriptTypes } from 'node:module'; console.log(stripTypeScriptTypes('const a: number = 1;')); // Prints: const a = 1; ``` Syntax that can be erased this way is called **erasable syntax**: - type annotations on variables, parameters and return values - `interface` and `type` declarations - `import type` and `export type`, and inline `type` modifiers on import names - `as` and `satisfies` expressions, generics, and `namespace` blocks that hold only types ## What Node deliberately does not do The design keeps Node fast and predictable by refusing several jobs a full TypeScript toolchain performs: 1. **No type checking.** A file with type errors runs anyway. Teams keep `tsc --noEmit` in CI or an editor check; Node only executes. 2. **No `tsconfig.json`.** Node never reads it, so options that live there, such as `paths` aliases or compiling newer syntax down to older JavaScript, have no effect. 3. **No code generation.** Constructs that need JavaScript to be *written*, not just deleted, fail: `enum`, parameter properties, namespaces with runtime code and `import x = require()` aliases throw `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`. 4. **No `.tsx`.** JSX files are not supported. 5. **No TypeScript inside `node_modules`.** Node refuses to strip files under a `node_modules` path, so dependencies must ship JavaScript. 6. **Not everywhere.** TypeScript is unsupported in the REPL, with `--check` and in `inspect`; `--eval` and STDIN accept it, with `--input-type` choosing the module system. ## How the module system is chosen Stripping does not convert between CommonJS and ES modules. Whatever syntax the file uses is what runs, and the format is decided exactly as it is for JavaScript files: | Extension | Runs as | |---|---| | `.ts` | decided like `.js`: the nearest `package.json` `"type"`, or syntax detection when there is none | | `.mts` | always an ES module, like `.mjs` | | `.cts` | always CommonJS, like `.cjs` | | `.tsx` | unsupported | ## Imports must name real files Node resolves specifiers against the file system, not against a compiler's rules, so a relative import must carry its real extension: `import { db } from './db.ts'`, not `'./db'` or `'./db.js'`. The same applies to `require('./db.ts')` in CommonJS. A type that is imported without the `type` keyword is treated as a value import; because the interface does not exist at run time, an ES module fails at link time with a `SyntaxError` saying the requested module does not provide an export with that name. Writing `import type { User }` fixes it. ## Where this leaves you in practice - Use `node file.ts` for scripts, tools and services whose code sticks to erasable syntax. - Run the type checker as its own step; a green `node` run says nothing about types. - Keep the editor honest by configuring the compiler to flag non-erasable syntax, so violations show up before Node rejects them at startup. - Reach for a third-party runner or a build step when you need full TypeScript syntax or `tsconfig.json` features; Node's documentation points to such packages for "full support". `--no-strip-types` turns the feature off, for example when another loader should own `.ts` files. Type stripping is a runtime convenience with sharp edges, and knowing exactly where those edges are is what interviewers listen for.

  • Why does a type error not stop `node server.ts` from running in Node.js 24?
    Because Node never runs the type checker. Stripping is a purely syntactic pass: it only has to recognise which tokens belong to the type system so it can blank them. Checking types needs the whole program, declaration files and the compiler's configuration, which is the TypeScript compiler's job. Keep `tsc --noEmit` in CI or a pre-commit step; Node only executes.
  • Can type stripping be switched off in Node.js 24, and why would you?
    Yes, with `--no-strip-types`. The flag was renamed from `--no-experimental-strip-types` in v24.12.0 when stripping became stable, and the old spelling is still listed as an accepted option. You would turn it off when you want a different loader or a build step to own `.ts` files, so Node's built-in behaviour cannot silently take over.

  • Node 24 type-checks a .ts file before running it.
  • Node reads tsconfig.json for paths and target when running .ts.
  • Running a .ts file on Node 24 still needs --experimental-strip-types.
  • Node compiles .ts to a .js file and caches it beside the source.
  • import './db' finds db.ts because Node tries the .ts extension.

Assumes Node.js 24: type stripping is on by default since v23.6.0 and v22.18.0, warning-free since v24.3.0 and stable since v24.12.0.