Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 133 ยท Modules and Packages

TypeScript in Node.js

Run .ts files directly in Node.js 24 with built-in type stripping - erasable syntax only, import type, file extensions, tsconfig for Node, type-checking with tsc and tsx or ts-node alternatives.

TypeScript is JavaScript with type annotations: you write function area(radius: number): number, a tool checks that you call it correctly, and the annotations disappear before the program runs. For years that meant a build step: compile every .ts file to .js, then run the output. Since Node.js 22.18 and 23.6, and so in Node.js 24 LTS, Node can run .ts files directly. You type node app.ts and it works, with no flags and no compiler.

The trick is called type stripping. Node does not understand types and does not check them. It simply blanks out the type annotations and runs what is left as ordinary JavaScript. That keeps Node small and fast, but it has consequences you must understand: what syntax is allowed, what is not checked, and how to get real type checking. This lesson covers all of it.

In our editor, make the first line of a node example the comment // ts and the code runs as TypeScript (the file is saved as main.mts, an ES module). For several .ts files, examples write them to disk and run them with node file.ts in a child process. If you are new to TypeScript itself, the TypeScript tutorial teaches the language; here we focus on running it with Node.

Your first TypeScript program in Node

Annotations, interfaces, type aliases and generics all work. After stripping, Node runs the remaining JavaScript.

Node.js Running TypeScript directly

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The last line prints strip, which is Node reporting how it handles TypeScript: by stripping types. The syntax Node must remove is everything that exists only for the type checker: annotations after names, interface and type declarations, generic parameters, as assertions, satisfies, the ! non-null operator and import type.

What stripping really does

Node replaces the type syntax with spaces, not by deleting it. Because every other character stays in the same line and column, stack traces and debugger positions still point at the right place in your .ts file, with no source map needed. You can watch it happen with module.stripTypeScriptTypes() (experimental, so Node prints a warning on stderr that we ignore here).

Node.js Seeing the blanks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

We replaced spaces with dots so you can count them: the annotation : number became blanks, the whole interface line became blanks, and each line stayed where it was. Nothing is checked, nothing is generated and nothing needs a tsconfig.json.

Types are not checked

This is the most important sentence in the lesson: running TypeScript with Node does not type-check it. A program with type errors runs happily, because the types are thrown away before execution.

Node.js Wrong types run anyway

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

'21' * 2 works in JavaScript because the string is converted, so we get 42, but input + input joins the strings and gives 2121. TypeScript would have caught the mistake; Node did not. To keep the safety, run the real compiler separately: tsc --noEmit checks the project and writes nothing. Typical setups run it in the editor (always) and in CI (to fail the build), while Node just executes the code.

Erasable syntax only

Stripping works only for syntax that can be erased and leaves valid JavaScript behind. A few TypeScript features are not erasable, because they generate real runtime code: enum, namespace with values, class parameter properties (constructor(public x: number)), and the old angle-bracket assertion <T>value. Node's default mode rejects them with a clear error.

Node.js An enum (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The program stops before running anything and prints SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode, and the output marks the whole enum block with > as the offending code (the source is main.mts in our editor, and the // ts line counts as line 1). Parameter properties give the same error with the text "TypeScript parameter property is not supported in strip-only mode", and namespaces say "TypeScript namespace declaration is not supported in strip-only mode".

The fix is to write the plain-JavaScript equivalent, which most modern TypeScript guides recommend anyway. A union of string literals or an as const object replaces an enum, and an explicit field replaces a parameter property.

Node.js Erasable replacements

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The as const object is a normal JavaScript object, and type Level = ... is erased. The same name can be both a value and a type, which is legal in TypeScript. You can ask the compiler to enforce this rule in your own project with the erasableSyntaxOnly option (see the tsconfig section), so unsupported syntax is flagged in your editor instead of at run time.

If you cannot give up enums, Node can also transform them: node --experimental-transform-types app.ts generates the runtime code. We cannot pass flags in our editor, so this is read-only; treat it as an escape hatch because it is a Node-specific feature, and other tools may not support the same code.

Importing between .ts files

Imports follow the same rules as in ES Modules, with two TypeScript-specific details. First, you must write the real file extension, .ts. Node does not rewrite anything, so import './types.ts' is the file name on disk. Second, you must mark type-only imports with import type or an inline type modifier, because Node cannot tell types from values: it would keep the import and then fail because the type does not exist at run time.

Node.js Two files and the type keyword

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

good.ts works. bad.ts fails with "The requested module './types.ts' does not provide an export named 'Point'", because Point was erased from types.ts but bad.ts still asks for it. noext.ts fails with ERR_MODULE_NOT_FOUND because the extension is missing. The compiler option verbatimModuleSyntax makes TypeScript itself report the bad.ts mistake, so you find it before running.

Two more rules about files:

  • .ts files are treated as ES modules or CommonJS following the same package.json "type" rules as .js. Use .mts and .cts to force one. (Our editor's // ts snippet is main.mts.)
  • .tsx (JSX) files are not supported by type stripping.

Not under node_modules

Node refuses to strip types inside node_modules. The reason is practical: a published package should ship plain JavaScript (plus .d.ts type files), so that it runs on any Node version and with any tool. If a dependency ships .ts sources, you get an error, which we can reproduce by faking an installed package:

Node.js TypeScript inside node_modules (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The code is ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING. If you author a library in TypeScript, compile it to JavaScript with tsc (or a bundler) and publish dist/ as described in Creating and Publishing Packages.

Errors and stack traces

Because stripping keeps positions, stack traces point at the correct line of your TypeScript file. This works even without source maps, and Node reports the .ts (or in our editor .mts) file name.

Node.js A TypeScript stack trace (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first call prints 42; the second throws TypeError: not a number: forty, and Node points at main.mts:5, the throw line (line numbers count the // ts marker as line 1). In a longer program the stack lists parseAge and its caller with exact lines. See Debugging and Diagnostics for reading traces.

A tsconfig.json for Node

Node ignores tsconfig.json completely when running files. Your editor and tsc read it. The recommended settings for a project that runs on Node's type stripping make the compiler enforce the same limits Node has:

JSON
{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}
Option Why it matters for Node
module / moduleResolution: nodenext Resolve files the way Node does (extensions required, exports maps honoured)
allowImportingTsExtensions Lets you write import './x.ts'; requires noEmit or rewriteRelativeImportExtensions
rewriteRelativeImportExtensions When you do compile with tsc, rewrites ./x.ts to ./x.js in the output
erasableSyntaxOnly Errors on enums, namespaces and parameter properties, matching Node's strip mode
verbatimModuleSyntax Forces import type for types, matching what Node needs
noEmit Only type-check; Node does the running
strict The standard safety net; always on

Add @types/node as a dev dependency so the editor knows about node:fs, process, Buffer and so on: npm install -D typescript @types/node.

Your options for running and checking

Approach What it does When to use
node app.ts Strips types, runs Scripts, tools, servers on Node 22.18+
node --watch app.ts Same, restarts on change Development
tsc --noEmit Type-check only CI and pre-commit
tsc then node dist/app.js Compile to JS, run the output Libraries, anything published
tsx app.ts A third-party runner using esbuild; supports enums, JSX and more When you need non-erasable features today
ts-node An older runner that can type-check while running; slower Legacy projects
node --experimental-transform-types app.ts Node transforms enums and namespaces too Experiments only

A common modern workflow: run with node during development (instant start-up, no build), type-check with tsc --noEmit in the editor and in CI, and compile to JavaScript only for code you publish.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does Node.js do with type annotations when you run node app.ts?

    Type stripping only removes the type syntax. Nothing is checked or generated, and positions stay the same so stack traces remain accurate.
  2. 2. Which of these fails in Node's default TypeScript mode?

    Enums generate runtime code, so they are not erasable syntax. Node stops with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX unless you use --experimental-transform-types.
  3. 3. How should you import an interface from another .ts file?

    You need the real .ts extension and a type marker (import type or the inline type modifier), so Node can erase the import. Without the marker the import survives and fails at run time.
  4. 4. Which command actually checks your types?

    Only the TypeScript compiler checks types. Node just runs the stripped code; use tsc --noEmit in your editor, scripts and CI.
  5. 5. Why do npm packages ship JavaScript instead of .ts files?

    Type stripping is disabled for files under node_modules (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), and plain JavaScript runs everywhere. Libraries compile to JS and add .d.ts files.

Summary

  • Node.js 22.18+/24 runs .ts files directly by stripping type syntax, with no flag, compiler or tsconfig.json; in our editor the first line // ts selects it.
  • Stripping blanks out types but keeps line and column positions, so stack traces point at your TypeScript source.
  • Node does not type-check; use tsc --noEmit (editor, CI) for safety.
  • Only erasable syntax works: no enum, value namespace, parameter properties or <T>x assertions. Use as const objects, explicit fields and as.
  • Import with real .ts extensions and mark type-only imports with import type or type; .tsx is unsupported.
  • Types are never stripped inside node_modules: publish compiled JavaScript plus .d.ts files.
  • Configure tsconfig.json with module: nodenext, erasableSyntaxOnly, verbatimModuleSyntax and noEmit so the compiler enforces Node's rules; add @types/node.
  • Alternatives are tsx, ts-node and a normal tsc build for libraries.

Next: Module Design Patterns shows how to organise the modules you write.