From bf518343d0536e1c1d46bc22eb286632c2f1dd20 Mon Sep 17 00:00:00 2001 From: Oliver Massaad Date: Sat, 14 Nov 2026 01:06:51 -0500 Subject: [PATCH 1/2] docs: add type stripping hub page Adds a high-level explainer for Node.js type stripping covering what it is, quick start, version guidance, FAQs, and links to deeper docs. Fixes nodejs/learn#34. --- pages/typescript/type-stripping.md | 111 +++++++++++++++++++++++++++++ site.json | 4 ++ 2 files changed, 115 insertions(+) create mode 100644 pages/typescript/type-stripping.md diff --git a/pages/typescript/type-stripping.md b/pages/typescript/type-stripping.md new file mode 100644 index 0000000..45a5dbb --- /dev/null +++ b/pages/typescript/type-stripping.md @@ -0,0 +1,111 @@ +--- +authors: olimasad +--- + +# Type stripping in Node.js + +**Type stripping** is Node.js's built-in way to run TypeScript. Node.js removes erasable TypeScript syntax (type annotations, interfaces, and similar), replaces it with whitespace, and executes the remaining JavaScript. It does **not** type-check your code and it does **not** transform TypeScript features that need new JavaScript to be generated. + +This page is a high-level overview. For a short runbook, see [Running TypeScript Natively](/learn/typescript/run-natively). For the detailed specification, see the [TypeScript API docs](https://nodejs.org/api/typescript.html#type-stripping). + +## What type stripping is + +TypeScript adds types on top of JavaScript. Much of that syntax is *erasable*: it exists only for the type checker and editors. Type stripping deletes that erasable syntax at runtime so `node` can run `.ts` / `.mts` / `.cts` files without a separate build step. + +```ts +function greet(name: string): string { + return `Hello, ${name}`; +} + +console.log(greet('Node')); +``` + +```bash +node greet.ts +``` + +Node.js ignores `tsconfig.json` when stripping types. Features that depend on `tsconfig` settings (path aliases, downlevel emit, and similar) are intentionally unsupported. Prefer [a TypeScript runner](/learn/typescript/run) or [transpilation](/learn/typescript/transpile) when you need those. + +## Quick start + +On Node.js **v22.18.0+** (and current release lines where type stripping is enabled by default), run a file that uses only erasable syntax: + +```bash +node example.ts +``` + +Disable the feature when you need to: + +```bash +node --no-strip-types example.ts +``` + +Module systems follow the same rules as JavaScript: + +- `.ts` follows the nearest `package.json` `"type"` field (like `.js`) +- `.mts` is always an ES module +- `.cts` is always CommonJS +- `.tsx` is not supported + +Import specifiers still need file extensions: `import './file.ts'`. + +## Which Node.js versions have it? + +| Support | Versions (summary) | +| --- | --- | +| Enabled by default | v22.18.0+, v23.6.0+, and current release lines that ship type stripping on by default | +| Marked stable | See the [History table in the API docs](https://nodejs.org/api/typescript.html#type-stripping) (for example v24.12.0 / v25.2.0) | + +Always check the docs for the exact line you run in production. Older minor versions may still require an experimental flag. + +## FAQ + +### Does `node file.ts` type-check my project? + +No. Use the TypeScript compiler (or your editor) for that: + +```bash +npx tsc --noEmit +``` + +A common workflow is: run with `node` for fast feedback, and run `tsc --noEmit` in CI. + +### What syntax is supported? + +Supported examples include type annotations, interfaces, type aliases, and `import type` / inline `type` imports. + +Not supported by type stripping alone (these need transform / a runner / `tsc` emit), including: + +- `enum` declarations +- parameter properties +- namespaces that contain runtime values +- import aliases +- experimental decorators (until they exist in JavaScript) + +Publishing packages as raw TypeScript under `node_modules` is also refused — Node.js will not strip types inside dependency trees. + +### Recommended `tsconfig.json` + +Match Node.js's erasable-syntax model with TypeScript **5.8+** (5.7+ is a common minimum in older guides): + +```json +{ + "compilerOptions": { + "target": "esnext", + "module": "nodenext", + "rewriteRelativeImportExtensions": true, + "erasableSyntaxOnly": true, + "verbatimModuleSyntax": true + } +} +``` + +Add `"noEmit": true` when you only execute `.ts` files and do not emit `.js` output. + +## Learn more + +- [Running TypeScript Natively](/learn/typescript/run-natively) +- [Running TypeScript with a runner](/learn/typescript/run) +- [Running TypeScript code using transpilation](/learn/typescript/transpile) +- [Node.js API: TypeScript / type stripping](https://nodejs.org/api/typescript.html#type-stripping) +- [TypeScript: `--erasableSyntaxOnly`](https://www.typescriptlang.org/tsconfig/#erasableSyntaxOnly) diff --git a/site.json b/site.json index 1515874..84ed836 100644 --- a/site.json +++ b/site.json @@ -311,6 +311,10 @@ "link": "/learn/typescript/introduction", "label": "Introduction to TypeScript" }, + { + "link": "/learn/typescript/type-stripping", + "label": "Type stripping in Node.js" + }, { "link": "/learn/typescript/run-natively", "label": "Running TypeScript Natively" From 1b538a5f1c68a7440765abdb6a8350e8c925715a Mon Sep 17 00:00:00 2001 From: Oliver Massaad Date: Sat, 14 Nov 2026 01:07:10 -0500 Subject: [PATCH 2/2] docs: link type stripping hub from TypeScript introduction --- pages/typescript/introduction.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pages/typescript/introduction.md b/pages/typescript/introduction.md index 703eada..4e3848d 100644 --- a/pages/typescript/introduction.md +++ b/pages/typescript/introduction.md @@ -114,3 +114,5 @@ TypeScript also includes powerful transformation capabilities, particularly for Okay, so we have some TypeScript code. Now how do we run it? There are few possible ways to run TypeScript code, we will cover all of them in the next articles. + +If you want the high-level overview of Node.js's built-in approach first, start with [Type stripping in Node.js](/learn/typescript/type-stripping).