From 1c6cb35fffed6ae69185425a39934d2204a3252e Mon Sep 17 00:00:00 2001
From: Scover <>
Date: Fri, 1 May 2026 15:08:33 +0200
Subject: [PATCH 01/14] Update types option docs for TypeScript 6.0
---
.../copy/en/handbook-v2/Type Declarations.md | 3 ++-
.../copy/en/options/typeRoots.md | 26 ++++++++++++++-----
.../copy/en/options/types.md | 22 +++++++++++-----
3 files changed, 38 insertions(+), 13 deletions(-)
diff --git a/packages/documentation/copy/en/handbook-v2/Type Declarations.md b/packages/documentation/copy/en/handbook-v2/Type Declarations.md
index c03614a85f96..08e2d3f2bdd5 100644
--- a/packages/documentation/copy/en/handbook-v2/Type Declarations.md
+++ b/packages/documentation/copy/en/handbook-v2/Type Declarations.md
@@ -85,7 +85,8 @@ For example, if you installed the `react` npm package, you can install its corre
npm install --save-dev @types/react
```
-TypeScript automatically finds type definitions under `node_modules/@types`, so there's no other step needed to get these types available in your program.
+When you import a package in your source code, TypeScript will automatically look for its type definitions, including definitions under `node_modules/@types`.
+If an `@types` package provides globals that you use without importing, such as `process` from `@types/node` or `describe` from `@types/jest`, add the package name to the [`types`](/tsconfig#types) field of your `tsconfig.json`.
### Your Own Definitions
diff --git a/packages/tsconfig-reference/copy/en/options/typeRoots.md b/packages/tsconfig-reference/copy/en/options/typeRoots.md
index 5fdb453bfa9e..d794b16e0bb2 100644
--- a/packages/tsconfig-reference/copy/en/options/typeRoots.md
+++ b/packages/tsconfig-reference/copy/en/options/typeRoots.md
@@ -3,19 +3,33 @@ display: "Type Roots"
oneline: "Specify multiple folders that act like `./node_modules/@types`."
---
-By default all _visible_ "`@types`" packages are included in your compilation.
-Packages in `node_modules/@types` of any enclosing folder are considered _visible_.
-For example, that means packages within `./node_modules/@types/`, `../node_modules/@types/`, `../../node_modules/@types/`, and so on.
+The `typeRoots` option specifies folders that act like `./node_modules/@types`.
+It changes where TypeScript looks when resolving type package names from [`types`](#types) and `/// ` directives.
-If `typeRoots` is specified, _only_ packages under `typeRoots` will be included. For example:
+In TypeScript 6.0 and later, [`types`](#types) defaults to `[]`, so specifying `typeRoots` does not by itself include every package under those folders.
+List the packages you need in `types`, or specify `"types": ["*"]` to include all packages under the configured `typeRoots`.
+
+For example:
```json tsconfig
{
"compilerOptions": {
- "typeRoots": ["./typings", "./vendor/types"]
+ "typeRoots": ["./typings", "./vendor/types"],
+ "types": ["node"]
}
}
```
-This config file will include _all_ packages under `./typings` and `./vendor/types`, and no packages from `./node_modules/@types`.
+This config file will look for the `node` type package under `./typings` and `./vendor/types`, and will not look for it under `./node_modules/@types`.
All paths are relative to the `tsconfig.json`.
+
+To include _all_ packages under `./typings` and `./vendor/types`, use:
+
+```json tsconfig
+{
+ "compilerOptions": {
+ "typeRoots": ["./typings", "./vendor/types"],
+ "types": ["*"]
+ }
+}
+```
diff --git a/packages/tsconfig-reference/copy/en/options/types.md b/packages/tsconfig-reference/copy/en/options/types.md
index 0b0f8f93744c..799f467435d0 100644
--- a/packages/tsconfig-reference/copy/en/options/types.md
+++ b/packages/tsconfig-reference/copy/en/options/types.md
@@ -3,23 +3,33 @@ display: "Types"
oneline: "Specify type package names to be included without being referenced in a source file."
---
-By default all _visible_ "`@types`" packages are included in your compilation.
-Packages in `node_modules/@types` of any enclosing folder are considered _visible_.
-For example, that means packages within `./node_modules/@types/`, `../node_modules/@types/`, `../../node_modules/@types/`, and so on.
+By default, no "`@types`" packages are included in the global scope unless they are referenced by your source files.
If `types` is specified, only packages listed will be included in the global scope. For instance:
```json tsconfig
{
"compilerOptions": {
- "types": ["node", "jest", "express"]
+ "types": ["node", "jest"]
}
}
```
-This `tsconfig.json` file will _only_ include `./node_modules/@types/node`, `./node_modules/@types/jest` and `./node_modules/@types/express`.
+This `tsconfig.json` file will _only_ include `./node_modules/@types/node` and `./node_modules/@types/jest`.
Other packages under `node_modules/@types/*` will not be included.
+To include all _visible_ "`@types`" packages, specify `"*"`.
+Packages in `node_modules/@types` of any enclosing folder are considered _visible_.
+For example, that means packages within `./node_modules/@types/`, `../node_modules/@types/`, `../../node_modules/@types/`, and so on.
+
+```json tsconfig
+{
+ "compilerOptions": {
+ "types": ["*"]
+ }
+}
+```
+
### What does this affect?
This option does not affect how `@types/*` are included in your application code, for example if you had the above `compilerOptions` example with code like:
@@ -32,7 +42,7 @@ moment().format("MMMM Do YYYY, h:mm:ss a");
The `moment` import would be fully typed.
-When you have this option set, by not including a module in the `types` array it:
+When a package is not included through the `types` array, it:
- Will not add globals to your project (e.g `process` in node, or `expect` in Jest)
- Will not have exports appear as auto-import recommendations
From af02d0ddfd7bccaa84f732d59e7b7f7018a7a835 Mon Sep 17 00:00:00 2001
From: Scover <>
Date: Fri, 1 May 2026 15:14:16 +0200
Subject: [PATCH 02/14] Update rootDir docs for TypeScript 6.0
---
.../copy/en/options/outDir.md | 2 +-
.../copy/en/options/rootDir.md | 26 +++++++++----------
2 files changed, 13 insertions(+), 15 deletions(-)
diff --git a/packages/tsconfig-reference/copy/en/options/outDir.md b/packages/tsconfig-reference/copy/en/options/outDir.md
index a205af13ac8c..cddbb61675b4 100644
--- a/packages/tsconfig-reference/copy/en/options/outDir.md
+++ b/packages/tsconfig-reference/copy/en/options/outDir.md
@@ -4,7 +4,7 @@ oneline: "Specify an output folder for all emitted files."
---
If specified, `.js` (as well as `.d.ts`, `.js.map`, etc.) files will be emitted into this directory.
-The directory structure of the original source files is preserved; see [`rootDir`](#rootDir) if the computed root is not what you intended.
+The directory structure of the original source files is preserved relative to [`rootDir`](#rootDir).
If not specified, `.js` files will be emitted in the same directory as the `.ts` files they were generated from:
diff --git a/packages/tsconfig-reference/copy/en/options/rootDir.md b/packages/tsconfig-reference/copy/en/options/rootDir.md
index ff7447a81013..71975e99220a 100644
--- a/packages/tsconfig-reference/copy/en/options/rootDir.md
+++ b/packages/tsconfig-reference/copy/en/options/rootDir.md
@@ -3,7 +3,7 @@ display: "Root Dir"
oneline: "Specify the root folder within your source files."
---
-**Default**: The longest common path of all non-declaration input files. If [`composite`](#composite) is set, the default is instead the directory containing the `tsconfig.json` file.
+**Default**: The directory containing the `tsconfig.json` file. If compiling files from the command line without a `tsconfig.json`, the default is the longest common path of all non-declaration input files.
When TypeScript compiles files, it keeps the same directory structure in the output directory as exists in the input directory.
@@ -20,30 +20,28 @@ MyProj
├── types.d.ts
```
-The inferred value for `rootDir` is the longest common path of all non-declaration input files, which in this case is `core/`.
-
If your [`outDir`](#outDir) was `dist`, TypeScript would write this tree:
```
MyProj
├── dist
-│ ├── a.js
-│ ├── b.js
-│ ├── sub
-│ │ ├── c.js
+│ ├── core
+│ │ ├── a.js
+│ │ ├── b.js
+│ │ ├── sub
+│ │ │ ├── c.js
```
-However, you may have intended for `core` to be part of the output directory structure.
-By setting `rootDir: "."` in `tsconfig.json`, TypeScript would write this tree:
+If you want `core` to be treated as the root of your source tree, set `rootDir: "core"` in `tsconfig.json`.
+TypeScript would then write this tree:
```
MyProj
├── dist
-│ ├── core
-│ │ ├── a.js
-│ │ ├── b.js
-│ │ ├── sub
-│ │ │ ├── c.js
+│ ├── a.js
+│ ├── b.js
+│ ├── sub
+│ │ ├── c.js
```
Importantly, `rootDir` **does not affect which files become part of the compilation**.
From a7dcf263237a60cc5d099083d485add443654134 Mon Sep 17 00:00:00 2001
From: Scover <>
Date: Fri, 1 May 2026 15:15:34 +0200
Subject: [PATCH 03/14] Update docs for TypeScript 6.0 defaults
---
packages/documentation/copy/en/handbook-v2/Basics.md | 11 +++++------
packages/documentation/copy/en/tutorials/Gulp.md | 6 ++++--
.../copy/en/options/libReplacement.md | 3 +--
packages/tsconfig-reference/copy/en/options/module.md | 2 ++
.../copy/en/options/noUncheckedSideEffectImports.md | 7 ++++---
packages/tsconfig-reference/copy/en/options/strict.md | 2 ++
packages/tsconfig-reference/copy/en/options/target.md | 4 +++-
7 files changed, 21 insertions(+), 14 deletions(-)
diff --git a/packages/documentation/copy/en/handbook-v2/Basics.md b/packages/documentation/copy/en/handbook-v2/Basics.md
index 79b870e76501..96df9defd63c 100644
--- a/packages/documentation/copy/en/handbook-v2/Basics.md
+++ b/packages/documentation/copy/en/handbook-v2/Basics.md
@@ -391,8 +391,8 @@ Template strings are a feature from a version of ECMAScript called ECMAScript 20
TypeScript has the ability to rewrite code from newer versions of ECMAScript to older ones such as ECMAScript 3 or ECMAScript 5 (a.k.a. ES5).
This process of moving from a newer or "higher" version of ECMAScript down to an older or "lower" one is sometimes called _downleveling_.
-By default TypeScript targets ES5, an extremely old version of ECMAScript.
-We could have chosen something a little bit more recent by using the [`target`](/tsconfig#target) option.
+By default TypeScript targets the most recent supported ECMAScript version.
+We could have chosen something older by using the [`target`](/tsconfig#target) option.
Running with `--target es2015` changes TypeScript to target ECMAScript 2015, meaning code should be able to run wherever ECMAScript 2015 is supported.
So running `tsc --target es2015 hello.ts` gives us the following output:
@@ -403,15 +403,14 @@ function greet(person, date) {
greet("Maddison", new Date());
```
-> While the default target is ES5, the great majority of current browsers support ES2015.
-> Most developers can therefore safely specify ES2015 or above as a target, unless compatibility with certain ancient browsers is important.
+> Modern runtimes support ES2015 and newer.
+> Most developers can therefore safely use a recent target unless compatibility with older browsers is important.
## Strictness
Different users come to TypeScript looking for different things in a type-checker.
Some people are looking for a more loose opt-in experience which can help validate only some parts of their program, and still have decent tooling.
-This is the default experience with TypeScript, where types are optional, inference takes the most lenient types, and there's no checking for potentially `null`/`undefined` values.
-Much like how `tsc` emits in the face of errors, these defaults are put in place to stay out of your way.
+You can configure TypeScript for a looser opt-in experience where types are optional, inference takes more lenient types, and there's less checking for potentially `null`/`undefined` values.
If you're migrating existing JavaScript, that might be a desirable first step.
In contrast, a lot of users prefer to have TypeScript validate as much as it can straight away, and that's why the language provides strictness settings as well.
diff --git a/packages/documentation/copy/en/tutorials/Gulp.md b/packages/documentation/copy/en/tutorials/Gulp.md
index 8aa1d0df8cc5..8300b1fe19e9 100644
--- a/packages/documentation/copy/en/tutorials/Gulp.md
+++ b/packages/documentation/copy/en/tutorials/Gulp.md
@@ -86,6 +86,7 @@ In the project root, `proj`, create the file `tsconfig.json`:
"files": ["src/main.ts"],
"compilerOptions": {
"noImplicitAny": true,
+ "module": "commonjs",
"target": "es5"
}
}
@@ -142,6 +143,7 @@ Finally, add `src/greet.ts` to `tsconfig.json`:
"files": ["src/main.ts", "src/greet.ts"],
"compilerOptions": {
"noImplicitAny": true,
+ "module": "commonjs",
"target": "es5"
}
}
@@ -155,14 +157,14 @@ node dist/main.js
```
Notice that even though we used ES2015 module syntax, TypeScript emitted CommonJS modules that Node uses.
-We'll stick with CommonJS for this tutorial, but you could set `module` in the options object to change this.
+We'll stick with CommonJS for this tutorial, but you could set `module` to another value to change this.
## Browserify
Now let's move this project from Node to the browser.
To do this, we'd like to bundle all our modules into one JavaScript file.
Fortunately, that's exactly what Browserify does.
-Even better, it lets us use the CommonJS module system used by Node, which is the default TypeScript emit.
+Even better, it lets us use the CommonJS module system used by Node.
That means our TypeScript and Node setup will transfer to the browser basically unchanged.
First, install browserify, [tsify](https://www.npmjs.com/package/tsify), and vinyl-source-stream.
diff --git a/packages/tsconfig-reference/copy/en/options/libReplacement.md b/packages/tsconfig-reference/copy/en/options/libReplacement.md
index 2b8069825609..14bd9a433fc1 100644
--- a/packages/tsconfig-reference/copy/en/options/libReplacement.md
+++ b/packages/tsconfig-reference/copy/en/options/libReplacement.md
@@ -18,5 +18,4 @@ For example, you could lock your `dom` libraries onto a specific version of [the
When installed, a package called `@typescript/lib-dom` should exist, and TypeScript would always look there when searching for `lib.dom.d.ts`.
The `--libReplacement` flag allows you to disable this behavior.
-If you're not using any `@typescript/lib-*` packages, you can now disable those package lookups with `--libReplacement false`.
-In the future, `--libReplacement false` may become the default, so if you currently rely on the behavior you should consider explicitly enabling it with `--libReplacement true`.
\ No newline at end of file
+If you are using `@typescript/lib-*` packages, explicitly enable those package lookups with `--libReplacement true`.
diff --git a/packages/tsconfig-reference/copy/en/options/module.md b/packages/tsconfig-reference/copy/en/options/module.md
index fef555737b1f..e4cd3e7d9ff3 100644
--- a/packages/tsconfig-reference/copy/en/options/module.md
+++ b/packages/tsconfig-reference/copy/en/options/module.md
@@ -3,6 +3,8 @@ display: "Module"
oneline: "Specify what module code is generated."
---
+**Default**: `esnext`
+
Sets the module system for the program. See the [theory behind TypeScript’s `module` option](/docs/handbook/modules/theory.html#the-module-output-format) and [its reference page](/docs/handbook/modules/reference.html#the-module-compiler-option) for more information. You very likely want `"nodenext"` for modern Node.js projects and `preserve` or `esnext` for code that will be bundled.
Changing `module` affects [`moduleResolution`](#moduleResolution) which [also has a reference page](/docs/handbook/modules/reference.html#the-moduleresolution-compiler-option).
diff --git a/packages/tsconfig-reference/copy/en/options/noUncheckedSideEffectImports.md b/packages/tsconfig-reference/copy/en/options/noUncheckedSideEffectImports.md
index e6d862efc733..33ae7b08d1cd 100644
--- a/packages/tsconfig-reference/copy/en/options/noUncheckedSideEffectImports.md
+++ b/packages/tsconfig-reference/copy/en/options/noUncheckedSideEffectImports.md
@@ -11,10 +11,11 @@ import "some-module";
These imports are often called *side effect imports* because the only useful behavior they can provide is by executing some side effect (like registering a global variable, or adding a polyfill to a prototype).
-By default, TypeScript will not check these imports for validity. If the import resolves to a valid source file, TypeScript will load and check the file.
-If no source file is found, TypeScript will silently ignore the import.
+By default, TypeScript checks these imports for validity. If the import resolves to a valid source file, TypeScript will load and check the file.
+If no source file is found, TypeScript will issue an error.
-This is surprising behavior, but it partially stems from modeling patterns in the JavaScript ecosystem.
+Older versions of TypeScript silently ignored unresolved side effect imports, but that behavior could hide typos.
+It partially stemmed from modeling patterns in the JavaScript ecosystem.
For example, this syntax has also been used with special loaders in bundlers to load CSS or other assets.
Your bundler might be configured in such a way where you can include specific `.css` files by writing something like the following:
diff --git a/packages/tsconfig-reference/copy/en/options/strict.md b/packages/tsconfig-reference/copy/en/options/strict.md
index cc35ee30ec00..fdd974a0f90c 100644
--- a/packages/tsconfig-reference/copy/en/options/strict.md
+++ b/packages/tsconfig-reference/copy/en/options/strict.md
@@ -3,6 +3,8 @@ display: "Strict"
oneline: "Enable all strict type-checking options."
---
+**Default**: `true`
+
The `strict` flag enables a wide range of type checking behavior that results in stronger guarantees of program correctness.
Turning this on is equivalent to enabling all of the _strict mode family_ options, which are outlined below.
You can then turn off individual strict mode family checks as needed.
diff --git a/packages/tsconfig-reference/copy/en/options/target.md b/packages/tsconfig-reference/copy/en/options/target.md
index b31b482ebb24..aafaa5c268e5 100644
--- a/packages/tsconfig-reference/copy/en/options/target.md
+++ b/packages/tsconfig-reference/copy/en/options/target.md
@@ -3,7 +3,9 @@ display: "Target"
oneline: "Set the JavaScript language version for emitted JavaScript and include compatible library declarations."
---
-Modern browsers support all ES6 features, so `ES6` is a good choice.
+**Default**: The most recent supported ECMAScript version.
+
+Modern runtimes support newer ECMAScript features, so a recent target is a good choice.
You might choose to set a lower target if your code is deployed to older environments, or a higher target if your code is guaranteed to run in newer environments.
The `target` setting changes which JS features are downleveled and which are left intact.
From 190e7db4450bcc5598053981d3bbc6b53fbaa2f9 Mon Sep 17 00:00:00 2001
From: Scover <>
Date: Fri, 1 May 2026 15:16:09 +0200
Subject: [PATCH 04/14] Update lib docs for TypeScript 6.0
---
packages/tsconfig-reference/copy/en/options/lib.md | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/packages/tsconfig-reference/copy/en/options/lib.md b/packages/tsconfig-reference/copy/en/options/lib.md
index fb0311a7aa7e..6082dbe115d7 100644
--- a/packages/tsconfig-reference/copy/en/options/lib.md
+++ b/packages/tsconfig-reference/copy/en/options/lib.md
@@ -30,16 +30,19 @@ In TypeScript 4.5, lib files can be overridden by npm modules, find out more [in
| `ES2021` | Additional APIs available in ES2021 - `promise.any`, `string.replaceAll` etc. |
| `ES2022` | Additional APIs available in ES2022 - `array.at`, `RegExp.hasIndices`, etc. |
| `ES2023` | Additional APIs available in ES2023 - `array.with`, `array.findLast`, `array.findLastIndex`, `array.toSorted`, `array.toReversed`, etc. |
+| `ES2024` | Additional APIs available in ES2024 - `Object.groupBy`, `Map.groupBy`, `Promise.withResolvers`, `ArrayBuffer`, `SharedArrayBuffer`, etc. |
+| `ES2025` | Additional APIs available in ES2025 - `RegExp.escape`, `Map` and `WeakMap` upsert methods, etc. |
| `ESNext` | Additional APIs available in ESNext - This changes as the JavaScript specification evolves |
| `DOM` | [DOM](https://developer.mozilla.org/docs/Glossary/DOM) definitions - `window`, `document`, etc. |
| `WebWorker` | APIs available in [WebWorker](https://developer.mozilla.org/docs/Web/API/Web_Workers_API/Using_web_workers) contexts |
| `ScriptHost` | APIs for the [Windows Script Hosting System](https://wikipedia.org/wiki/Windows_Script_Host) |
+In TypeScript 6.0 and later, `DOM` includes the contents that were previously split into `DOM.Iterable` and `DOM.AsyncIterable`.
+
### Individual library components
| Name |
| ------------------------- |
-| `DOM.Iterable` |
| `ES2015.Core` |
| `ES2015.Collection` |
| `ES2015.Generator` |
From c54265f2ec25a287136e2173c4bf7e7de93bf5b5 Mon Sep 17 00:00:00 2001
From: Scover <>
Date: Fri, 1 May 2026 15:17:31 +0200
Subject: [PATCH 05/14] Update docs for ES5 target deprecation
---
.../copy/en/handbook-v2/More on Functions.md | 2 +-
packages/documentation/copy/en/tutorials/Gulp.md | 4 ++--
.../copy/en/tutorials/Migrating from JavaScript.md | 4 ++--
.../copy/en/options/downlevelIteration.md | 3 +++
.../tsconfig-reference/copy/en/options/explainFiles.md | 8 ++++----
packages/tsconfig-reference/copy/en/options/target.md | 3 ++-
6 files changed, 14 insertions(+), 10 deletions(-)
diff --git a/packages/documentation/copy/en/handbook-v2/More on Functions.md b/packages/documentation/copy/en/handbook-v2/More on Functions.md
index 4d40edb5bada..e31efe167190 100644
--- a/packages/documentation/copy/en/handbook-v2/More on Functions.md
+++ b/packages/documentation/copy/en/handbook-v2/More on Functions.md
@@ -775,7 +775,7 @@ const args = [8, 5] as const;
const angle = Math.atan2(...args);
```
-Using rest arguments may require turning on [`downlevelIteration`](/tsconfig#downlevelIteration) when targeting older runtimes.
+Using rest arguments may require a recent [`target`](/tsconfig#target) when targeting older runtimes.
diff --git a/packages/documentation/copy/en/tutorials/Gulp.md b/packages/documentation/copy/en/tutorials/Gulp.md
index 8300b1fe19e9..47fe12f81d4d 100644
--- a/packages/documentation/copy/en/tutorials/Gulp.md
+++ b/packages/documentation/copy/en/tutorials/Gulp.md
@@ -87,7 +87,7 @@ In the project root, `proj`, create the file `tsconfig.json`:
"compilerOptions": {
"noImplicitAny": true,
"module": "commonjs",
- "target": "es5"
+ "target": "es2015"
}
}
```
@@ -144,7 +144,7 @@ Finally, add `src/greet.ts` to `tsconfig.json`:
"compilerOptions": {
"noImplicitAny": true,
"module": "commonjs",
- "target": "es5"
+ "target": "es2015"
}
}
```
diff --git a/packages/documentation/copy/en/tutorials/Migrating from JavaScript.md b/packages/documentation/copy/en/tutorials/Migrating from JavaScript.md
index 4a8ba2ecfbca..9434036bc301 100644
--- a/packages/documentation/copy/en/tutorials/Migrating from JavaScript.md
+++ b/packages/documentation/copy/en/tutorials/Migrating from JavaScript.md
@@ -48,7 +48,7 @@ Let's create a bare-bones one for our project:
"compilerOptions": {
"outDir": "./built",
"allowJs": true,
- "target": "es5"
+ "target": "es2015"
},
"include": ["./src/**/*"]
}
@@ -59,7 +59,7 @@ Here we're specifying a few things to TypeScript:
1. Read in any files it understands in the `src` directory (with [`include`](/tsconfig#include)).
2. Accept JavaScript files as inputs (with [`allowJs`](/tsconfig#allowJs)).
3. Emit all of the output files in `built` (with [`outDir`](/tsconfig#outDir)).
-4. Translate newer JavaScript constructs down to an older version like ECMAScript 5 (using [`target`](/tsconfig#target)).
+4. Translate newer JavaScript constructs down to a specific ECMAScript version (using [`target`](/tsconfig#target)).
At this point, if you try running `tsc` at the root of your project, you should see output files in the `built` directory.
The layout of files in `built` should look identical to the layout of `src`.
diff --git a/packages/tsconfig-reference/copy/en/options/downlevelIteration.md b/packages/tsconfig-reference/copy/en/options/downlevelIteration.md
index 9f2812fc7d0f..5f6890415ac1 100644
--- a/packages/tsconfig-reference/copy/en/options/downlevelIteration.md
+++ b/packages/tsconfig-reference/copy/en/options/downlevelIteration.md
@@ -3,6 +3,9 @@ display: "Downlevel Iteration"
oneline: "Emit more compliant, but verbose and less performant JavaScript for iteration."
---
+This option is deprecated in TypeScript 6.0 and later.
+It only affects ES5 emit, and `target: "es5"` is also deprecated.
+
Downleveling is TypeScript's term for transpiling to an older version of JavaScript.
This flag is to enable support for a more accurate implementation of how modern JavaScript iterates through new concepts in older JavaScript runtimes.
diff --git a/packages/tsconfig-reference/copy/en/options/explainFiles.md b/packages/tsconfig-reference/copy/en/options/explainFiles.md
index d907a3c702da..f198c238285b 100644
--- a/packages/tsconfig-reference/copy/en/options/explainFiles.md
+++ b/packages/tsconfig-reference/copy/en/options/explainFiles.md
@@ -19,7 +19,7 @@ Using a `tsconfig.json` which has `explainFiles` set to true:
```json
{
"compilerOptions": {
- "target": "es5",
+ "target": "es2015",
"module": "commonjs",
"explainFiles": true
}
@@ -31,9 +31,9 @@ Running TypeScript against this folder would have output like this:
```
❯ tsc
node_modules/typescript/lib/lib.d.ts
- Default library for target 'es5'
-node_modules/typescript/lib/lib.es5.d.ts
- Library referenced via 'es5' from file 'node_modules/typescript/lib/lib.d.ts'
+ Default library for target 'es2015'
+node_modules/typescript/lib/lib.es2015.d.ts
+ Library referenced via 'es2015' from file 'node_modules/typescript/lib/lib.d.ts'
node_modules/typescript/lib/lib.dom.d.ts
Library referenced via 'dom' from file 'node_modules/typescript/lib/lib.d.ts'
node_modules/typescript/lib/lib.webworker.importscripts.d.ts
diff --git a/packages/tsconfig-reference/copy/en/options/target.md b/packages/tsconfig-reference/copy/en/options/target.md
index aafaa5c268e5..b7ddb829a79a 100644
--- a/packages/tsconfig-reference/copy/en/options/target.md
+++ b/packages/tsconfig-reference/copy/en/options/target.md
@@ -7,9 +7,10 @@ oneline: "Set the JavaScript language version for emitted JavaScript and include
Modern runtimes support newer ECMAScript features, so a recent target is a good choice.
You might choose to set a lower target if your code is deployed to older environments, or a higher target if your code is guaranteed to run in newer environments.
+The lowest supported target is `ES2015`.
The `target` setting changes which JS features are downleveled and which are left intact.
-For example, an arrow function `() => this` will be turned into an equivalent `function` expression if `target` is ES5 or lower.
+For example, an arrow function `() => this` will be left as-is when targeting `ES2015` or higher.
Changing `target` also changes the default value of [`lib`](#lib).
You may "mix and match" `target` and `lib` settings as desired, but you could just set `target` for convenience.
From 6e23b5030d1a7e02b1408af1755e3904a8d054f7 Mon Sep 17 00:00:00 2001
From: Scover <>
Date: Fri, 1 May 2026 15:19:04 +0200
Subject: [PATCH 06/14] Update module resolution docs for TypeScript 6.0
---
.../copy/en/modules-reference/Reference.md | 15 +++++-----
.../copy/en/modules-reference/Theory.md | 6 ++--
.../en/tutorials/Migrating from JavaScript.md | 2 +-
.../copy/en/options/baseUrl.md | 30 ++++++++-----------
.../copy/en/options/moduleResolution.md | 4 +--
5 files changed, 25 insertions(+), 32 deletions(-)
diff --git a/packages/documentation/copy/en/modules-reference/Reference.md b/packages/documentation/copy/en/modules-reference/Reference.md
index 5695c26ea8e2..d622aab04345 100644
--- a/packages/documentation/copy/en/modules-reference/Reference.md
+++ b/packages/documentation/copy/en/modules-reference/Reference.md
@@ -747,17 +747,16 @@ Multiple file paths can be provided for a path mapping. If resolution fails for
#### `baseUrl`
-> `baseUrl` was designed for use with AMD module loaders. If you aren’t using an AMD module loader, you probably shouldn’t use `baseUrl`. Since TypeScript 4.1, `baseUrl` is no longer required to use [`paths`](#paths) and should not be used just to set the directory `paths` values are resolved from.
+> `baseUrl` was designed for use with AMD module loaders. If you aren’t using an AMD module loader, you probably shouldn’t use `baseUrl`. Since TypeScript 4.1, `baseUrl` is no longer required to use [`paths`](#paths), and in TypeScript 6.0 it is deprecated.
-The `baseUrl` compiler option can be combined with any `moduleResolution` mode and specifies a directory that bare specifiers (module specifiers that don’t begin with `./`, `../`, or `/`) are resolved from. `baseUrl` has a higher precedence than [`node_modules` package lookups](#node_modules-package-lookups) in `moduleResolution` modes that support them.
-
-When performing a `baseUrl` lookup, resolution proceeds with the same rules as other relative path resolutions. For example, in a `moduleResolution` mode that supports [extensionless relative paths](#extensionless-relative-paths) a module specifier `"some-file"` may resolve to `/src/some-file.ts` if `baseUrl` is set to `/src`.
+For code that used `baseUrl` as a common prefix for [`paths`](#paths), remove `baseUrl` and add that prefix to each `paths` entry.
+For code that used `baseUrl` as a lookup root for arbitrary bare specifiers, use an explicit catch-all `paths` entry instead.
Resolution of relative module specifiers are never affected by the `baseUrl` option.
#### `node_modules` package lookups
-Node.js treats module specifiers that aren’t relative paths, absolute paths, or URLs as references to packages that it looks up in `node_modules` subdirectories. Bundlers conveniently adopted this behavior to allow their users to use the same dependency management system, and often even the same dependencies, as they would in Node.js. All of TypeScript’s `moduleResolution` options except `classic` support `node_modules` lookups. (`classic` supports lookups in `node_modules/@types` when other means of resolution fail, but never looks for packages in `node_modules` directly.) Every `node_modules` package lookup has the following structure (beginning after higher precedence bare specifier rules, like `paths`, `baseUrl`, self-name imports, and package.json `"imports"` lookups have been exhausted):
+Node.js treats module specifiers that aren’t relative paths, absolute paths, or URLs as references to packages that it looks up in `node_modules` subdirectories. Bundlers conveniently adopted this behavior to allow their users to use the same dependency management system, and often even the same dependencies, as they would in Node.js. All of TypeScript’s module resolution modes for modern code support `node_modules` lookups. Every `node_modules` package lookup has the following structure (beginning after higher precedence bare specifier rules, like `paths`, self-name imports, and package.json `"imports"` lookups have been exhausted):
1. For each ancestor directory of the importing file, if a `node_modules` directory exists within it:
1. If a directory with the same name as the package exists within `node_modules`:
@@ -1153,7 +1152,7 @@ import { foo } from "pkg";
Recall that in `--module nodenext --moduleResolution nodenext`, the `--module` setting first [determines](#module-format-detection) whether the import will be emitted to the `.js` file as an `import` or `require` call, then passes that information to TypeScript’s module resolver, which decides whether to match `"import"` or `"require"` conditions in `"pkg"`’s package.json `"exports"` accordingly. Let’s assume that there’s no package.json in scope of this file. The file extension is `.ts`, so the output file extension will be `.js`, which Node.js will interpret as CommonJS, so TypeScript will emit this `import` as a `require` call. So, the module resolver will use the `require` condition as it resolves `"exports"` from `"pkg"`.
-The same process happens in `--moduleResolution bundler`, but the rules for deciding whether to emit an `import` or `require` call for this import statement will be different, since `--moduleResolution bundler` necessitates using [`--module esnext`](#es2015-es2020-es2022-esnext) or [`--module preserve`](#preserve). In both of those modes, ESM `import` declarations always emit as ESM `import` declarations, so TypeScript’s module resolver will receive that information and use the `"import"` condition as it resolves `"exports"` from `"pkg"`.
+The same process happens in `--moduleResolution bundler`, but the rules for deciding whether to emit an `import` or `require` call for this import statement will be different. If `--moduleResolution bundler` is paired with [`--module esnext`](#es2015-es2020-es2022-esnext) or [`--module preserve`](#preserve), ESM `import` declarations emit as ESM `import` declarations, so TypeScript’s module resolver will receive that information and use the `"import"` condition as it resolves `"exports"` from `"pkg"`.
This explanation may be somewhat unintuitive, since `--moduleResolution bundler` is usually used in combination with `--noEmit`—bundlers typically process raw `.ts` files and perform module resolution on untransformed `import`s or `require`s. However, for consistency, TypeScript still uses the hypothetical emit decided by `module` to inform module resolution and type checking. This makes [`--module preserve`](#preserve) the best choice whenever a runtime or bundler is operating on raw `.ts` files, since it implies no transformation. Under `--module preserve --moduleResolution bundler`, you can write imports and requires in the same file that will resolve with the `import` and `require` conditions, respectively:
@@ -1166,7 +1165,7 @@ import pkg2 = require("pkg"); // Resolved with "require" condition
#### Implied and enforced options
-- `--moduleResolution bundler` must be paired with `--module esnext` or `--module preserve`.
+- `--moduleResolution bundler` can be paired with `--module esnext`, `--module preserve`, or `--module commonjs`.
- `--moduleResolution bundler` implies `--allowSyntheticDefaultImports`.
#### Supported features
@@ -1184,7 +1183,7 @@ import pkg2 = require("pkg"); // Resolved with "require" condition
### `node10` (formerly known as `node`)
-`--moduleResolution node` was renamed to `node10` (keeping `node` as an alias for backward compatibility) in TypeScript 5.0. It reflects the CommonJS module resolution algorithm as it existed in Node.js versions earlier than v12. It should no longer be used.
+`--moduleResolution node` was renamed to `node10` (keeping `node` as an alias for backward compatibility) in TypeScript 5.0. It reflects the CommonJS module resolution algorithm as it existed in Node.js versions earlier than v12. It is deprecated in TypeScript 6.0 and should no longer be used.
#### Supported features
diff --git a/packages/documentation/copy/en/modules-reference/Theory.md b/packages/documentation/copy/en/modules-reference/Theory.md
index 5e64354c5bb7..9088456e2e31 100644
--- a/packages/documentation/copy/en/modules-reference/Theory.md
+++ b/packages/documentation/copy/en/modules-reference/Theory.md
@@ -240,11 +240,11 @@ and still claim to implement “standards-compliant ESM.” Needless to say, Typ
The available `moduleResolution` options are:
-- [**`classic`**](/docs/handbook/modules/reference.html#classic): TypeScript’s oldest module resolution mode, this is unfortunately the default when `module` is set to anything other than `commonjs`, `node16`, or `nodenext`. It was probably made to provide best-effort resolution for a wide range of [RequireJS](https://requirejs.org/docs/api.html#packages) configurations. It should not be used for new projects (or even old projects that don’t use RequireJS or another AMD module loader), and is scheduled for deprecation in TypeScript 6.0.
-- [**`node10`**](/docs/handbook/modules/reference.html#node10-formerly-known-as-node): Formerly known as `node`, this is the unfortunate default when `module` is set to `commonjs`. It’s a pretty good model of Node.js versions older than v12, and sometimes it’s a passable approximation of how most bundlers do module resolution. It supports looking up packages from `node_modules`, loading directory `index.js` files, and omitting `.js` extensions in relative module specifiers. Because Node.js v12 introduced different module resolution rules for ES modules, though, it’s a very bad model of modern versions of Node.js. It should not be used for new projects.
+- [**`classic`**](/docs/handbook/modules/reference.html#classic): TypeScript’s oldest module resolution mode. It was probably made to provide best-effort resolution for a wide range of [RequireJS](https://requirejs.org/docs/api.html#packages) configurations. It is deprecated in TypeScript 6.0 and should not be used.
+- [**`node10`**](/docs/handbook/modules/reference.html#node10-formerly-known-as-node): Formerly known as `node`, this reflects Node.js versions older than v12. It supports looking up packages from `node_modules`, loading directory `index.js` files, and omitting `.js` extensions in relative module specifiers. Because Node.js v12 introduced different module resolution rules for ES modules, though, it’s a very bad model of modern versions of Node.js. It is deprecated in TypeScript 6.0 and should not be used for new projects.
- [**`node16`**](/docs/handbook/modules/reference.html#node16-nodenext-1): This is the counterpart of `--module node16` and `--module node18` and is set by default with that `module` setting. Node.js v12 and later support both ESM and CJS, each of which uses its own module resolution algorithm. In Node.js, module specifiers in import statements and dynamic `import()` calls are not allowed to omit file extensions or `/index.js` suffixes, while module specifiers in `require` calls are. This module resolution mode understands and enforces this restriction where necessary, as determined by the [module format detection rules](#module-format-detection) instated by `--module node16`/`node18`. (For `node16` and `nodenext`, `module` and `moduleResolution` go hand-in-hand: setting one to `node16` or `nodenext` while setting the other to something else is an error.)
- [**`nodenext`**](/docs/handbook/modules/reference.html#node16-nodenext-1): Currently identical to `node16`, this is the counterpart of `--module nodenext` and is set by default with that `module` setting. It’s intended to be a forward-looking mode that will support new Node.js module resolution features as they’re added.
-- [**`bundler`**](/docs/handbook/modules/reference.html#bundler): Node.js v12 introduced some new module resolution features for importing npm packages—the `"exports"` and `"imports"` fields of `package.json`—and many bundlers adopted those features without also adopting the stricter rules for ESM imports. This module resolution mode provides a base algorithm for code targeting a bundler. It supports `package.json` `"exports"` and `"imports"` by default, but can be configured to ignore them. It requires setting `module` to `esnext`.
+- [**`bundler`**](/docs/handbook/modules/reference.html#bundler): Node.js v12 introduced some new module resolution features for importing npm packages—the `"exports"` and `"imports"` fields of `package.json`—and many bundlers adopted those features without also adopting the stricter rules for ESM imports. This module resolution mode provides a base algorithm for code targeting a bundler. It supports `package.json` `"exports"` and `"imports"` by default, but can be configured to ignore them.
### TypeScript imitates the host’s module resolution, but with types
diff --git a/packages/documentation/copy/en/tutorials/Migrating from JavaScript.md b/packages/documentation/copy/en/tutorials/Migrating from JavaScript.md
index 9434036bc301..c92600e0c42b 100644
--- a/packages/documentation/copy/en/tutorials/Migrating from JavaScript.md
+++ b/packages/documentation/copy/en/tutorials/Migrating from JavaScript.md
@@ -219,7 +219,7 @@ If TypeScript complains about a package like `lodash`, you can just write
npm install -S @types/lodash
```
-If you're using a module option other than `commonjs`, you'll need to set your [`moduleResolution`](/tsconfig#moduleResolution) option to `node`.
+If you're using a modern module option, set your [`moduleResolution`](/tsconfig#moduleResolution) option to match your runtime or bundler.
After that, you'll be able to import lodash with no issues, and get accurate completions.
diff --git a/packages/tsconfig-reference/copy/en/options/baseUrl.md b/packages/tsconfig-reference/copy/en/options/baseUrl.md
index b3317157652f..3faafe2e8d58 100644
--- a/packages/tsconfig-reference/copy/en/options/baseUrl.md
+++ b/packages/tsconfig-reference/copy/en/options/baseUrl.md
@@ -3,24 +3,18 @@ display: "Base URL"
oneline: "Specify the base directory to resolve bare specifier module names."
---
-Sets a base directory from which to resolve bare specifier module names. For example, in the directory structure:
+This option is deprecated in TypeScript 6.0 and later.
+It was designed for use in conjunction with AMD module loaders in the browser, and is not recommended in any other context.
+As of TypeScript 4.1, `baseUrl` is no longer required to be set when using [`paths`](#paths).
-```
-project
-├── ex.ts
-├── hello
-│ └── world.ts
-└── tsconfig.json
-```
-
-With `"baseUrl": "./"`, TypeScript will look for files starting at the same folder as the `tsconfig.json`:
+If you previously used `baseUrl` as a common prefix for paths, move the prefix into the `paths` entries instead:
-```ts
-import { helloWorld } from "hello/world";
-
-console.log(helloWorld);
+```json tsconfig
+{
+ "compilerOptions": {
+ "paths": {
+ "hello/*": ["./hello/*"]
+ }
+ }
+}
```
-
-This resolution has higher priority than lookups from `node_modules`.
-
-This feature was designed for use in conjunction with AMD module loaders in the browser, and is not recommended in any other context. As of TypeScript 4.1, `baseUrl` is no longer required to be set when using [`paths`](#paths).
\ No newline at end of file
diff --git a/packages/tsconfig-reference/copy/en/options/moduleResolution.md b/packages/tsconfig-reference/copy/en/options/moduleResolution.md
index 81a58e345e95..ef1dbb031f20 100644
--- a/packages/tsconfig-reference/copy/en/options/moduleResolution.md
+++ b/packages/tsconfig-reference/copy/en/options/moduleResolution.md
@@ -6,8 +6,8 @@ oneline: "Specify how TypeScript looks up a file from a given module specifier."
Specify the module resolution strategy:
- `'node16'` or `'nodenext'` for modern versions of Node.js. Node.js v12 and later supports both ECMAScript imports and CommonJS `require`, which resolve using different algorithms. These `moduleResolution` values, when combined with the corresponding [`module`](#module) values, picks the right algorithm for each resolution based on whether Node.js will see an `import` or `require` in the output JavaScript code.
-- `'node10'` (previously called `'node'`) for Node.js versions older than v10, which only support CommonJS `require`. You probably won't need to use `node10` in modern code.
+- `'node10'` (previously called `'node'`) for Node.js versions older than v10, which only support CommonJS `require`. This is deprecated in TypeScript 6.0.
- `'bundler'` for use with bundlers. Like `node16` and `nodenext`, this mode supports package.json `"imports"` and `"exports"`, but unlike the Node.js resolution modes, `bundler` never requires file extensions on relative paths in imports.
-- `'classic'` was used in TypeScript before the release of 1.6. `classic` should not be used.
+- `'classic'` was used in TypeScript before the release of 1.6. This is deprecated in TypeScript 6.0 and should not be used.
There are reference pages explaining the [theory behind TypeScript’s module resolution](https://www.typescriptlang.org/docs/handbook/modules/theory.html#module-resolution) and the [details of each option](/docs/handbook/modules/reference.html#the-moduleresolution-compiler-option).
From ed93c908a20fbcb1b0cf2a9a8d346629c28f0313 Mon Sep 17 00:00:00 2001
From: Scover <>
Date: Fri, 1 May 2026 15:19:55 +0200
Subject: [PATCH 07/14] Update module emit docs for TypeScript 6.0
---
.../documentation/copy/en/handbook-v2/Modules.md | 2 +-
.../copy/en/project-config/Project References.md | 6 ------
.../copy/en/reference/Namespaces and Modules.md | 4 ++--
.../documentation/copy/en/reference/Namespaces.md | 14 +-------------
.../tsconfig-reference/copy/en/options/module.md | 8 ++++++++
.../tsconfig-reference/copy/en/options/outFile.md | 5 ++++-
6 files changed, 16 insertions(+), 23 deletions(-)
diff --git a/packages/documentation/copy/en/handbook-v2/Modules.md b/packages/documentation/copy/en/handbook-v2/Modules.md
index d84f9f9e7575..7266e132e1fa 100644
--- a/packages/documentation/copy/en/handbook-v2/Modules.md
+++ b/packages/documentation/copy/en/handbook-v2/Modules.md
@@ -28,7 +28,7 @@ Before we start, it's important to understand what TypeScript considers a module
The JavaScript specification declares that any JavaScript files without an `import` declaration, `export`, or top-level `await` should be considered a script and not a module.
-Inside a script file variables and types are declared to be in the shared global scope, and it's assumed that you'll either use the [`outFile`](/tsconfig#outFile) compiler option to join multiple input files into one output file, or use multiple `