diff --git a/packages/documentation/copy/en/modules-reference/Reference.md b/packages/documentation/copy/en/modules-reference/Reference.md index 082d8918ced5..5695c26ea8e2 100644 --- a/packages/documentation/copy/en/modules-reference/Reference.md +++ b/packages/documentation/copy/en/modules-reference/Reference.md @@ -201,7 +201,7 @@ declare module "*.html" { This section discusses the details of each `module` compiler option value. See the [_Module output format_](/docs/handbook/modules/theory.html#the-module-output-format) theory section for more background on what the option is and how it fits into the overall compilation process. In brief, the `module` compiler option was historically only used to control the output module format of emitted JavaScript files. The more recent `node16`, `node18`, and `nodenext` values, however, describe a wide range of characteristics of Node.js’s module system, including what module formats are supported, how the module format of each file is determined, and how different module formats interoperate. -### `node16`, `node18`, `nodenext` +### `node16`, `node18`, `node20`, `nodenext` Node.js supports both CommonJS and ECMAScript modules, with specific rules for which format each file can be and how the two formats are allowed to interoperate. `node16`, `node18`, and `nodenext` describe the full range of behavior for Node.js’s dual-format module system, and **emit files in either CommonJS or ESM format**. This is different from every other `module` option, which are runtime-agnostic and force all output files into a single format, leaving it to the user to ensure the output is valid for their runtime. @@ -1121,7 +1121,7 @@ import mod = require("./mod"); // `require` algorithm due to syntax (emit #### Implied and enforced options -- `--moduleResolution node16` and `nodenext` must be paired with [`--module node16`, `node18`, or `nodenext`](#node16-node18-nodenext). +- `--moduleResolution node16` and `nodenext` must be paired with [`--module node16`, `node18`, `node20`, or `nodenext`](#node16-node18-node20-nodenext). #### Supported features diff --git a/packages/documentation/copy/en/modules-reference/Theory.md b/packages/documentation/copy/en/modules-reference/Theory.md index ddcb510339e5..3c54f7f9b4ac 100644 --- a/packages/documentation/copy/en/modules-reference/Theory.md +++ b/packages/documentation/copy/en/modules-reference/Theory.md @@ -105,16 +105,16 @@ The `module` compiler option provides this information to the compiler. Its prim The available `module` settings are -- [**`node16`**](/docs/handbook/modules/reference.html#node16-node18-nodenext): Reflects the module system of Node.js v16+, which supports ES modules and CJS modules side-by-side with particular interoperability and detection rules. -- [**`node18`**](/docs/handbook/modules/reference.html#node16-node18-nodenext): Reflects the module system of Node.js v18+, which adds support for import attributes. -- [**`nodenext`**](/docs/handbook/modules/reference.html#node16-node18-nodenext): A moving target reflecting the latest Node.js versions as Node.js’s module system evolves. As of TypeScript 5.8, `nodenext` supports `require` of ECMAScript modules. +- [**`node16`**](/docs/handbook/modules/reference.html#node16-node18-node20-nodenext): Reflects the module system of Node.js v16+, which supports ES modules and CJS modules side-by-side with particular interoperability and detection rules. +- [**`node18`**](/docs/handbook/modules/reference.html#node16-node18-node20-nodenext): Reflects the module system of Node.js v18+, which adds support for import attributes. +- [**`nodenext`**](/docs/handbook/modules/reference.html#node16-node18-node20-nodenext): A moving target reflecting the latest Node.js versions as Node.js’s module system evolves. As of TypeScript 5.8, `nodenext` supports `require` of ECMAScript modules. - [**`es2015`**](/docs/handbook/modules/reference.html#es2015-es2020-es2022-esnext): Reflects the ES2015 language specification for JavaScript modules (the version that first introduced `import` and `export` to the language). - [**`es2020`**](/docs/handbook/modules/reference.html#es2015-es2020-es2022-esnext): Adds support for `import.meta` and `export * as ns from "mod"` to `es2015`. - [**`es2022`**](/docs/handbook/modules/reference.html#es2015-es2020-es2022-esnext): Adds support for top-level `await` to `es2020`. - [**`esnext`**](/docs/handbook/modules/reference.html#es2015-es2020-es2022-esnext): Currently identical to `es2022`, but will be a moving target reflecting the latest ECMAScript specifications, as well as module-related Stage 3+ proposals that are expected to be included in upcoming specification versions. - **[`commonjs`](/docs/handbook/modules/reference.html#commonjs), [`system`](/docs/handbook/modules/reference.html#system), [`amd`](/docs/handbook/modules/reference.html#amd), and [`umd`](/docs/handbook/modules/reference.html#umd)**: Each emits everything in the module system named, and assumes everything can be successfully imported into that module system. These are no longer recommended for new projects and will not be covered in detail by this documentation. -> Node.js’s rules for module format detection and interoperability make it incorrect to specify `module` as `esnext` or `commonjs` for projects that run in Node.js, even if all files emitted by `tsc` are ESM or CJS, respectively. The only correct `module` settings for projects that intend to run in Node.js are `node16` and `nodenext`. While the emitted JavaScript for an all-ESM Node.js project might look identical between compilations using `esnext` and `nodenext`, the type checking can differ. See the [reference section on `nodenext`](/docs/handbook/modules/reference.html#node16-node18-nodenext) for more details. +> Node.js’s rules for module format detection and interoperability make it incorrect to specify `module` as `esnext` or `commonjs` for projects that run in Node.js, even if all files emitted by `tsc` are ESM or CJS, respectively. The only correct `module` settings for projects that intend to run in Node.js are `node16` and `nodenext`. While the emitted JavaScript for an all-ESM Node.js project might look identical between compilations using `esnext` and `nodenext`, the type checking can differ. See the [reference section on `nodenext`](/docs/handbook/modules/reference.html#node16-node18-node20-nodenext) for more details. ### Module format detection diff --git a/packages/documentation/copy/en/project-config/Compiler Options.md b/packages/documentation/copy/en/project-config/Compiler Options.md index 5e0028a1f983..72eaa57dc7f3 100644 --- a/packages/documentation/copy/en/project-config/Compiler Options.md +++ b/packages/documentation/copy/en/project-config/Compiler Options.md @@ -868,7 +868,7 @@ tsc app.ts util.ts --target esnext --outfile index.js --moduleResolution

classic, node10/node, node16, nodenext, or bundler

-

Node10 if module is CommonJS; Node16 if module is Node16 or Node18; NodeNext if module is NodeNext; Bundler if module is Preserve; Classic otherwise.

+

Node10 if module is CommonJS; Node16 if module is Node16, Node18, or Node20; NodeNext if module is NodeNext; Bundler if module is Preserve; Classic otherwise.

@@ -1462,7 +1462,7 @@ tsc app.ts util.ts --target esnext --outfile index.js --target

es3, es5, es6/es2015, es2016, es2017, es2018, es2019, es2020, es2021, es2022, es2023, es2024, or esnext

-

ES5

+

es2023 if module is node20; esnext if module is nodenext; ES5 otherwise.

diff --git a/packages/tsconfig-reference/copy/en/options/module.md b/packages/tsconfig-reference/copy/en/options/module.md index b9355c20fd64..fef555737b1f 100644 --- a/packages/tsconfig-reference/copy/en/options/module.md +++ b/packages/tsconfig-reference/copy/en/options/module.md @@ -87,13 +87,14 @@ export const twoPi = valueOfPi * 2; In addition to the base functionality of `ES2015`/`ES6`, `ES2020` adds support for [dynamic `import`s](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import), and [`import.meta`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta) while `ES2022` further adds support for [top level `await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#top_level_await). -#### `node16`/`node18`/`nodenext` +#### `node16`/`node18`/`node20`/`nodenext` -The `node16`, `node18`, and `nodenext` modes integrate with Node's [native ECMAScript Module support](https://nodejs.org/api/esm.html). The emitted JavaScript uses either `CommonJS` or `ES2020` output depending on the file extension and the value of the `type` setting in the nearest `package.json`. Module resolution also works differently. You can learn more in the [handbook](/docs/handbook/esm-node.html) and [Modules Reference](/docs/handbook/modules/reference.html#node16-node18-nodenext). +The `node16`, `node18`, `node20`, and `nodenext` modes integrate with Node's [native ECMAScript Module support](https://nodejs.org/api/esm.html). The emitted JavaScript uses either `CommonJS` or `ES2020` output depending on the file extension and the value of the `type` setting in the nearest `package.json`. Module resolution also works differently. You can learn more in the [handbook](/docs/handbook/esm-node.html) and [Modules Reference](/docs/handbook/modules/reference.html#node16-node18-node20-nodenext). - `node16` is available from TypeScript 4.7 - `node18` is available from TypeScript 5.8 as a replacement for `node16`, with added support for import attributes. -- `nodenext` is available from TypeScript 4.7, but its behavior changes with the latest stable versions of Node.js. As of TypeScript 5.8, `nodenext` supports `require` of ECMAScript modules. +- `node20` adds support for require(ESM). +- `nodenext` is available from TypeScript 4.7, but its behavior changes with the latest stable versions of Node.js. `--module nodenext` implies the floating `--target esnext`. #### `preserve` diff --git a/packages/tsconfig-reference/scripts/tsconfigRules.ts b/packages/tsconfig-reference/scripts/tsconfigRules.ts index 2783b481e4ad..991666ba6a4e 100644 --- a/packages/tsconfig-reference/scripts/tsconfigRules.ts +++ b/packages/tsconfig-reference/scripts/tsconfigRules.ts @@ -239,7 +239,7 @@ export const defaultsForOptions = { ], moduleResolution: [ "`Node10` if [`module`](#module) is `CommonJS`;", - "`Node16` if [`module`](#module) is `Node16` or `Node18`;", + "`Node16` if [`module`](#module) is `Node16`, `Node18`, or `Node20`;", "`NodeNext` if [`module`](#module) is `NodeNext`;", "`Bundler` if [`module`](#module) is `Preserve`;", "`Classic` otherwise.", @@ -265,7 +265,11 @@ export const defaultsForOptions = { useUnknownInCatchVariables: trueIf("strict"), strictPropertyInitialization: trueIf("strict"), strictNullChecks: trueIf("strict"), - target: "ES5", + target: [ + "`es2023` if [`module`](#module) is `node20`;", + "`esnext` if [`module`](#module) is `nodenext`;", + "`ES5` otherwise.", + ], useDefineForClassFields: [ "`true` if [`target`](#target) is `ES2022` or higher, including `ESNext`;", "`false` otherwise.", diff --git a/packages/typescriptlang-org/src/redirects/setupRedirects.ts b/packages/typescriptlang-org/src/redirects/setupRedirects.ts index e86d7eb8612e..b33008fe834e 100644 --- a/packages/typescriptlang-org/src/redirects/setupRedirects.ts +++ b/packages/typescriptlang-org/src/redirects/setupRedirects.ts @@ -51,13 +51,17 @@ export const setupRedirects = ( addRedirects(veryOldRedirects) addRedirects(handbookRedirects) addRedirects({ - "/docs/handbook/esm-node": "/docs/handbook/modules/reference.html#node16-node18-nodenext", - "/docs/handbook/esm-node.html": "/docs/handbook/modules/reference.html#node16-node18-nodenext", + "/docs/handbook/esm-node": + "/docs/handbook/modules/reference.html#node16-node18-node20-nodenext", + "/docs/handbook/esm-node.html": + "/docs/handbook/modules/reference.html#node16-node18-node20-nodenext", "/docs/handbook/modules": "/docs/handbook/modules/introduction.html", "/docs/handbook/modules.html": "/docs/handbook/modules/introduction.html", - "/docs/handbook/module-resolution": "/docs/handbook/modules/theory.html#module-resolution", - "/docs/handbook/module-resolution.html": "/docs/handbook/modules/theory.html#module-resolution", - }); + "/docs/handbook/module-resolution": + "/docs/handbook/modules/theory.html#module-resolution", + "/docs/handbook/module-resolution.html": + "/docs/handbook/modules/theory.html#module-resolution", + }) // These have been replaced by the real output in the handbook // addRedirects({ // "/assets/typescript-handbook.epub": "/docs/handbook/intro.html",