From f1b2e1ca712e49224b397e6d01afe729c3929905 Mon Sep 17 00:00:00 2001
From: Herrtian <70463940+Herrtian@users.noreply.github.com>
Date: Sat, 23 May 2026 14:17:14 +0200
Subject: [PATCH] docs: clarify TypeScript type stripping behavior

---
 pages/typescript/run-natively.md | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/pages/typescript/run-natively.md b/pages/typescript/run-natively.md
index a5df048..9a913aa 100644
--- a/pages/typescript/run-natively.md
+++ b/pages/typescript/run-natively.md
@@ -6,6 +6,8 @@ authors: AugustinMauroy, khaosdoctor, jakebailey, robpalme
 
 You can write code that's valid TypeScript directly in Node.js without the need to transpile it first.
 
+Node.js runs TypeScript through a lightweight process called type stripping. It removes erasable TypeScript syntax, such as type annotations and interfaces, then runs the remaining JavaScript.
+
 If you are using v22.18.0 or later and your source code contains only [erasable TypeScript syntax](https://devblogs.microsoft.com/typescript/announcing-typescript-5-8-beta/#the---erasablesyntaxonly-option), you can execute TypeScript code without any flags.
 
 ```bash
@@ -18,7 +20,13 @@ If you are using a version less than v22.18.0, you can use the `--experimental-s
 node --experimental-strip-types example.ts
 ```
 
-And that's it! You can now run TypeScript code directly in Node.js without the need to transpile it first, and use TypeScript to catch type-related errors.
+And that's it! You can now run TypeScript code directly in Node.js without the need to transpile it first.
+
+Node.js does not type check your code when it runs TypeScript files. Use the TypeScript compiler separately if you want to catch type-related errors:
+
+```bash
+npx tsc --noEmit
+```
 
 You can disable it via [`--no-experimental-strip-types`](https://nodejs.org/docs/latest-v22.x/api/cli.html#--no-experimental-strip-types) flag if needed.
 
@@ -40,6 +48,18 @@ The support for TypeScript in Node.js has some constraints to keep in mind:
 
 You can get more information on the [API docs](https://nodejs.org/docs/latest-v22.x/api/typescript.html#typescript-features).
 
+### Type stripping
+
+Type stripping only works for TypeScript syntax that can be removed without changing the runtime JavaScript. This includes common type-only syntax such as type annotations, interfaces, type aliases, and `import type`.
+
+Syntax that requires JavaScript code generation is not handled by type stripping alone. Examples include `enum`, parameter properties, namespaces with runtime code, and import aliases. Use `--experimental-transform-types`, a runner, or a separate transpilation step if your project needs those features.
+
+### Type checking
+
+Running a `.ts` file with `node` is not the same as running `tsc`. Node.js executes the file after stripping supported type syntax, but it does not report type errors.
+
+For development, a common setup is to run Node.js directly for quick feedback and run `tsc --noEmit` in a separate command or CI job for type checking.
+
 ### Configuration
 
 The Node.js TypeScript loader ([Amaro](https://github.com/nodejs/amaro)) does not need or use `tsconfig.json` to run TypeScript code.