diff --git a/src/content/configuration/experiments.mdx b/src/content/configuration/experiments.mdx index 23ad8ae0b2d4..fd9dac5c12f8 100644 --- a/src/content/configuration/experiments.mdx +++ b/src/content/configuration/experiments.mdx @@ -29,6 +29,7 @@ Available options: - [`futureDefaults`](#experimentsfuturedefaults) - [`lazyCompilation`](#experimentslazycompilation) - [`outputModule`](#experimentsoutputmodule) +- [`typescript`](#experimentstypescript) - `syncWebAssembly`: Support the old WebAssembly like in webpack 4. - `layers`: Enable module and chunk layers, removed and works without additional options since `5.102.0`. - `topLevelAwait`: Transforms a module into an `async` module when an `await` is used at the top level. Starting from webpack version `5.83.0` (however, in versions prior to that, you can enable it by setting `experiments.topLevelAwait` to `true`), this feature is enabled by default, removed and works without additional options since `5.102.0`. @@ -403,3 +404,33 @@ export default { }, }; ``` + +### experiments.typescript + + + +Enable native TypeScript support. With the flag turned on, webpack compiles `.ts`, `.cts`, and `.mts` files (and the matching `data:text/typescript` and `data:application/typescript` data URIs) directly, without any external loader. Under the hood it calls Node.js's built-in [`module.stripTypeScriptTypes`](https://nodejs.org/api/module.html#modulestriptypescripttypescode-options). + +- Type: `boolean` +- Default: `false` (auto-enabled by [`experiments.futureDefaults`](#experimentsfuturedefaults)) +- Requires: Node.js >= 22.6 for the stable `mode: "strip"` API. + +```js +export default { + experiments: { + typescript: true, + }, + entry: "./src/index.ts", +}; +``` + +Enabling the flag also wires up sensible defaults: default rules for `.ts` / `.cts` / `.mts`, `.ts` added to extension resolution (before `.js`), `extensionAlias` so an `import "./foo.js"` also tries `./foo.ts` (and `.cjs` / `.mjs` → `.cts` / `.mts`), [`tsconfig.json` resolution](/configuration/resolve/#resolvetsconfig), and the `"typescript"` conditional-exports key so monorepo packages can ship `.ts` sources via `package.json#exports`. + +W> The transform only **erases types**. It does **not** perform type checking, and it does not handle JSX / `.tsx` or non-erasable TypeScript syntax (`enum`, `namespace` with runtime members, parameter-property constructors, `export =`, decorator metadata). These are the same constraints TypeScript enforces with the [`erasableSyntaxOnly`](https://www.typescriptlang.org/tsconfig/#erasableSyntaxOnly) tsconfig option. + +For type checking, pair the flag with `tsc --noEmit` or [`fork-ts-checker-webpack-plugin`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin). For JSX or non-erasable TypeScript syntax, keep using `ts-loader` or `swc-loader`. + +The webpack repo ships two reference examples: + +- [`examples/typescript`](https://github.com/webpack/webpack/tree/main/examples/typescript) for the built-in `experiments.typescript` setup. +- [`examples/typescript-non-erasable`](https://github.com/webpack/webpack/tree/main/examples/typescript-non-erasable) for the `ts-loader` fallback when non-erasable syntax is required.