Skip to content

Commit

Permalink
doc: improve type stripping documentation
Browse files Browse the repository at this point in the history
PR-URL: #56916
Reviewed-By: Jacob Smith <jacob@frende.me>
Reviewed-By: Pietro Marchini <pietro.marchini94@gmail.com>
  • Loading branch information
marco-ippolito authored and targos committed Feb 7, 2025
1 parent 888d2ac commit 7353266
Showing 1 changed file with 12 additions and 10 deletions.
22 changes: 12 additions & 10 deletions doc/api/typescript.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,14 +55,16 @@ added: v22.6.0

> Stability: 1.1 - Active development
The flag [`--no-experimental-strip-types`][] prevents Node.js from running TypeScript
files. By default Node.js will execute only files that contain no
TypeScript features that require transformation, such as enums.
Node.js will replace inline type annotations with whitespace,
By default Node.js will execute TypeScript files that contains only
erasable TypeScript syntax.
Node.js will replace TypeScript syntax with whitespace,
and no type checking is performed.
To enable the transformation of such features
use the flag [`--experimental-transform-types`][].
TypeScript features that depend on settings within `tsconfig.json`,
To enable the transformation of non erasable TypeScript syntax, which requires JavaScript code generation,
such as `enum` declarations, parameter properties use the flag [`--experimental-transform-types`][].
To disable this feature, use the flag [`--no-experimental-strip-types`][].

Node.js ignores `tsconfig.json` files and therefore
features that depend on settings within `tsconfig.json`,
such as paths or converting newer JavaScript syntax to older standards, are
intentionally unsupported. To get full TypeScript support, see [Full TypeScript support][].

Expand All @@ -71,7 +73,7 @@ By intentionally not supporting syntaxes that require JavaScript code
generation, and by replacing inline types with whitespace, Node.js can run
TypeScript code without the need for source maps.

Type stripping works with most versions of TypeScript
Type stripping is compatible with most versions of TypeScript
but we recommend version 5.7 or newer with the following `tsconfig.json` settings:

```json
Expand Down Expand Up @@ -139,7 +141,7 @@ This will result in [`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`][] error:

```ts
// This namespace is exporting a value
namespace A {
namespace A {
export let x = 1
}
```
Expand Down Expand Up @@ -204,9 +206,9 @@ with `#`.
[CommonJS]: modules.md
[ES Modules]: esm.md
[Full TypeScript support]: #full-typescript-support
[`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`]: errors.md#err_unsupported_typescript_syntax
[`--experimental-transform-types`]: cli.md#--experimental-transform-types
[`--no-experimental-strip-types`]: cli.md#--no-experimental-strip-types
[`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`]: errors.md#err_unsupported_typescript_syntax
[`tsconfig` "paths"]: https://www.typescriptlang.org/tsconfig/#paths
[`tsx`]: https://tsx.is/
[`verbatimModuleSyntax`]: https://www.typescriptlang.org/tsconfig/#verbatimModuleSyntax
Expand Down

0 comments on commit 7353266

Please sign in to comment.