From 5e2ee9a075eb3223628af00d8608ce29a10be486 Mon Sep 17 00:00:00 2001 From: johnnyreilly Date: Mon, 9 Nov 2026 16:37:12 +0000 Subject: [PATCH 1/4] feat: node 26 and README --- .github/workflows/benchmark.yml | 2 +- .github/workflows/comparison-tests.yml | 6 +- .github/workflows/format.yml | 2 +- .github/workflows/knip.yml | 2 +- .github/workflows/lint.yml | 2 +- .github/workflows/release.yml | 2 +- .github/workflows/test-probe.yml | 6 +- README.md | 638 +++++++++---------------- 8 files changed, 243 insertions(+), 417 deletions(-) diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml index 43f918a82..24ef1fe45 100644 --- a/.github/workflows/benchmark.yml +++ b/.github/workflows/benchmark.yml @@ -51,7 +51,7 @@ jobs: - uses: actions/setup-node@v7 with: - node-version: 24 + node-version: 26 cache: npm - uses: ./.github/actions/build-ts-loader diff --git a/.github/workflows/comparison-tests.yml b/.github/workflows/comparison-tests.yml index 45ded2fcc..8301c584c 100644 --- a/.github/workflows/comparison-tests.yml +++ b/.github/workflows/comparison-tests.yml @@ -13,7 +13,7 @@ jobs: - uses: actions/setup-node@v7 with: - node-version: 24 + node-version: 26 cache: npm - uses: ./.github/actions/build-ts-loader @@ -30,7 +30,7 @@ jobs: - uses: actions/setup-node@v7 with: - node-version: 24 + node-version: 26 cache: npm - uses: ./.github/actions/build-ts-loader @@ -47,7 +47,7 @@ jobs: - uses: actions/setup-node@v7 with: - node-version: 24 + node-version: 26 cache: npm - uses: ./.github/actions/build-ts-loader diff --git a/.github/workflows/format.yml b/.github/workflows/format.yml index c25c66ea1..0cbf62633 100644 --- a/.github/workflows/format.yml +++ b/.github/workflows/format.yml @@ -12,7 +12,7 @@ jobs: - uses: actions/setup-node@v7 with: - node-version: 24 + node-version: 26 cache: npm - name: install diff --git a/.github/workflows/knip.yml b/.github/workflows/knip.yml index 45f6a3ae6..4e4136269 100644 --- a/.github/workflows/knip.yml +++ b/.github/workflows/knip.yml @@ -12,7 +12,7 @@ jobs: - uses: actions/setup-node@v7 with: - node-version: 24 + node-version: 26 cache: npm - name: install diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index e6f5ef50f..80fae79f0 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -12,7 +12,7 @@ jobs: - uses: actions/setup-node@v7 with: - node-version: 24 + node-version: 26 cache: npm - uses: ./.github/actions/build-ts-loader diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index af5aa9af9..39916af73 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -18,7 +18,7 @@ jobs: - name: install node uses: actions/setup-node@v7 with: - node-version: 24 + node-version: 26 registry-url: https://registry.npmjs.org/ - uses: ./.github/actions/build-ts-loader diff --git a/.github/workflows/test-probe.yml b/.github/workflows/test-probe.yml index 9d2e98a14..f0b862843 100644 --- a/.github/workflows/test-probe.yml +++ b/.github/workflows/test-probe.yml @@ -39,7 +39,7 @@ jobs: - uses: actions/setup-node@v7 with: - node-version: 24 + node-version: 26 cache: npm - uses: ./.github/actions/build-ts-loader @@ -68,7 +68,7 @@ jobs: - uses: actions/setup-node@v7 with: - node-version: 24 + node-version: 26 cache: npm - uses: ./.github/actions/build-ts-loader @@ -97,7 +97,7 @@ jobs: - uses: actions/setup-node@v7 with: - node-version: 24 + node-version: 26 cache: npm - uses: ./.github/actions/build-ts-loader diff --git a/README.md b/README.md index 02ecf9993..6b1009569 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# TypeScript loader for webpack +# `ts-loader` - TypeScript loader for webpack [![npm version](https://img.shields.io/npm/v/ts-loader.svg)](https://www.npmjs.com/package/ts-loader) [![ci](https://github.com/TypeStrong/ts-loader/actions/workflows/ci.yml/badge.svg)](https://github.com/TypeStrong/ts-loader/actions/workflows/ci.yml) @@ -6,229 +6,110 @@ [![node version](https://img.shields.io/node/v/ts-loader.svg)](https://www.npmjs.com/package/ts-loader) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) -
-

-

ts-loader

- -

- This is the TypeScript loader for webpack. -
-
- Installation - · - Report Bug - · - Request Feature -

-

- -## Table of Contents - - - -- [Getting Started](#getting-started) - - [Installation](#installation) - - [Running](#running) - - [Examples](#examples) - - [Faster Builds](#faster-builds) - - [Babel](#babel) - - [Compatibility](#compatibility) - - [Configuration](#configuration) - - [`devtool` / sourcemaps](#devtool--sourcemaps) - - [Code Splitting and Loading Other Resources](#code-splitting-and-loading-other-resources) - - [Declaration Files (.d.ts)](#declaration-files-dts) - - [Failing the build on TypeScript compilation error](#failing-the-build-on-typescript-compilation-error) - - [`paths` module resolution](#paths-module-resolution) - - [Options](#options) - - [Loader Options](#loader-options) - - [transpileOnly](#transpileonly) - - [resolveModuleName and resolveTypeReferenceDirective](#resolvemodulename-and-resolvetypereferencedirective) - - [getCustomTransformers](#getcustomtransformers) - - [logInfoToStdOut](#loginfotostdout) - - [logLevel](#loglevel) - - [silent](#silent) - - [ignoreDiagnostics](#ignorediagnostics) - - [reportFiles](#reportfiles) - - [configFile](#configfile) - - [compiler](#compiler) - - [colors](#colors) - - [errorFormatter](#errorformatter) - - [instance](#instance) - - [appendTsSuffixTo](#appendtssuffixto) - - [appendTsxSuffixTo](#appendtsxsuffixto) - - [useCaseSensitiveFileNames](#usecasesensitivefilenames) - - [allowTsInNodeModules](#allowtsinnodemodules) - - [projectReferences](#projectreferences) - - [Usage with webpack watch](#usage-with-webpack-watch) - - [Hot Module replacement](#hot-module-replacement) -- [Contributing](#contributing) -- [History](#history) -- [License](#license) - - - -## Getting Started - -### Installation +`ts-loader` lets webpack compile your TypeScript files. It type checks your code and reports TypeScript errors as part of your webpack build. -``` -yarn add ts-loader --dev -``` - -or +This README covers **v10**, which is in beta. v10 uses TypeScript 7's native compiler API. If you are on TypeScript 6 or earlier, use v9 (`npm install ts-loader --save-dev`) and see the [v9 README](https://github.com/TypeStrong/ts-loader/tree/main#readme). -``` -npm install ts-loader --save-dev -``` +## Getting started -v10 is currently in beta and published under the `next` dist-tag; to try it, install `ts-loader@next` instead. The command above installs v9, which supports the classic TypeScript compiler API. - -You will also need to install TypeScript 7.1+ if you have not already. `ts-loader` compiles through TypeScript's native `typescript/sync` API, which older versions of TypeScript do not provide. Until TypeScript 7.1 has a stable release, install the beta: +### 1. Install ``` -yarn add typescript@beta --dev +npm install --save-dev ts-loader@next typescript@beta ``` or ``` -npm install typescript@beta --save-dev +pnpm add --save-dev ts-loader@next typescript@beta ``` -### Running +`ts-loader` v10 needs TypeScript 7.1 or later. Until TypeScript 7.1 and `ts-loader` v10 have stable releases, install them from the `beta` and `next` tags as above. -Use webpack like normal, including `webpack --watch` and `webpack-dev-server`, or through another -build system using the [Node.js API](https://webpack.js.org/api/node/). +### 2. Configure webpack -### Examples +Create or update `webpack.config.js`: -For a minimal webpack 5 setup using `ts-loader` v10 with TypeScript 7, see [examples/simple](examples/simple/). +```javascript +module.exports = { + mode: 'development', + devtool: 'inline-source-map', + entry: './app.ts', + output: { + filename: 'bundle.js', + }, + resolve: { + // Let webpack resolve imports without an extension to .ts and .tsx files + extensions: ['.ts', '.tsx', '.js'], + // Let `import './foo.js'` find `foo.ts` (TypeScript's ESM import style) + extensionAlias: { + '.js': ['.js', '.ts'], + '.cjs': ['.cjs', '.cts'], + '.mjs': ['.mjs', '.mts'], + }, + }, + module: { + rules: [ + // Send .ts, .cts, .mts and .tsx files through ts-loader + { test: /\.([cm]?ts|tsx)$/, loader: 'ts-loader' }, + ], + }, +}; +``` -### Faster Builds +### 3. Add a `tsconfig.json` -As your project becomes bigger, compilation time increases linearly. It's because typescript's semantic checker has to inspect all files on every rebuild. -The simple solution is to disable it by using the `transpileOnly: true` option, but doing so leaves you without type checking, and without declaration files unless your project uses [`isolatedDeclarations`](#declaration-files-dts). +```json +{ + "compilerOptions": { + "sourceMap": true + } +} +``` -You probably don't want to give up type checking; that's rather the point of TypeScript. So what you can do is use the [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin). -It runs the type checker on a separate process, so your build remains fast thanks to `transpileOnly: true` but you still have the type checking. +[`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) holds your TypeScript options, so your editor, the `tsc` command and `ts-loader` all use the same settings. -> **Note:** fork-ts-checker-webpack-plugin may not support TypeScript 7 yet. Check its documentation before relying on it with `ts-loader` v10. +### 4. Run webpack -### Babel +Run webpack as usual: `webpack`, `webpack --watch`, `webpack-dev-server`, or the [Node.js API](https://webpack.js.org/api/node/). If your code has a TypeScript error, webpack reports it and the build fails. -`ts-loader` works very well in combination with [babel](https://babeljs.io/) and [babel-loader](https://github.com/babel/babel-loader). Chain them so that `ts-loader` runs first, for example `use: ['babel-loader', 'ts-loader']` (webpack applies loaders from right to left). +For a complete working setup, see [examples/simple](examples/simple/). -### Compatibility +## Compatibility - TypeScript: 7.1+ -- webpack: 4.x+ and 5.x+ -- node: 22.x+ - -A full test suite runs on each pull request. It runs on Linux, macOS and Windows, testing `ts-loader` against a pinned TypeScript 7.1 build and against TypeScript@next, on Node.js 22, 24 and 26. Comparison tests run against webpack 5 only; execution tests run against both webpack 4 and webpack 5. - -If you become aware of issues not caught by the test suite then please let us know. Better yet, write a test and submit it in a PR! - -### Configuration - -1. Create or update `webpack.config.js` like so: - - ```javascript - module.exports = { - mode: 'development', - devtool: 'inline-source-map', - entry: './app.ts', - output: { - filename: 'bundle.js', - }, - resolve: { - // Add `.ts` and `.tsx` as a resolvable extension. - extensions: ['.ts', '.tsx', '.js'], - // Add support for TypeScripts fully qualified ESM imports. - extensionAlias: { - '.js': ['.js', '.ts'], - '.cjs': ['.cjs', '.cts'], - '.mjs': ['.mjs', '.mts'], - }, - }, - module: { - rules: [ - // all files with a `.ts`, `.cts`, `.mts` or `.tsx` extension will be handled by `ts-loader` - { test: /\.([cm]?ts|tsx)$/, loader: 'ts-loader' }, - ], - }, - }; - ``` - -2. Add a [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file. (The one below is super simple; but you can tweak this to your hearts desire) - - ```json - { - "compilerOptions": { - "sourceMap": true - } - } - ``` - -The [tsconfig.json](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file controls -TypeScript-related options so that your IDE, the `tsc` command, and this loader all share the -same options. - -#### `devtool` / sourcemaps - -If you want to be able to debug your original source then you can thanks to the magic of sourcemaps. There are 2 steps to getting this set up with `ts-loader` and webpack. - -First, for `ts-loader` to produce **sourcemaps**, you will need to set the [tsconfig.json](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html) option as `"sourceMap": true`. - -Second, you need to set the `devtool` option in your `webpack.config.js` to support the type of sourcemaps you want. To make your choice have a read of the [`devtool` webpack docs](https://webpack.js.org/configuration/devtool/). You may be somewhat daunted by the choice available. You may also want to vary the sourcemap strategy depending on your build environment. Here are some example strategies for different environments: - -- `devtool: 'inline-source-map'` - Solid sourcemap support; the best "all-rounder". Works well with karma-webpack (not all strategies do) -- `devtool: 'eval-cheap-module-source-map'` - Best support for sourcemaps whilst debugging. -- `devtool: 'source-map'` - Separate, full sourcemap files that work with minifiers; typically you might use this in Production - -### Code Splitting and Loading Other Resources - -Loading css and other resources is possible but you will need to make sure that -you have defined the `require` function in a [declaration file](https://www.typescriptlang.org/docs/handbook/writing-declaration-files.html). - -```typescript -declare var require: { - (path: string): T; - (paths: string[], callback: (...modules: any[]) => void): void; - ensure: ( - paths: string[], - callback: (require: (path: string) => T) => void, - ) => void; -}; -``` +- webpack: 4.x and 5.x +- Node.js: 22+ -Then you can simply require assets or chunks per the [webpack documentation](https://webpack.js.org/guides/code-splitting/). +The test suite runs on every pull request on Linux, macOS and Windows, against TypeScript 7.1 and TypeScript@next, on Node.js 22, 24 and 26. If you find a problem the tests don't catch, please [open an issue](https://github.com/TypeStrong/ts-loader/issues), or better yet, send a PR with a test. -```javascript -require('!style!css!./style.css'); -``` +## Guides -The same basic process is required for code splitting. In this case, you `import` modules you need but you -don't directly use them. Instead you require them at [split points](https://webpack.js.org/guides/code-splitting/). See [this example](test/comparison-tests/codeSplitting) and [this example](test/comparison-tests/es6codeSplitting) for more details. +### Faster builds -TypeScript also supports ECMAScript's `import()` calls, which import a module and return a promise to that module. webpack treats these as split points too - details on usage can be found [here](https://webpack.js.org/guides/code-splitting/#dynamic-imports). Happy code splitting! +Type checking takes longer as your project grows, because TypeScript checks every file on each rebuild. Setting the [`transpileOnly`](#transpileonly) option to `true` skips type checking, which makes builds much faster, but you lose type errors (and declaration files, unless you use [`isolatedDeclarations`](#declaration-files-dts)). -### Declaration Files (.d.ts) +To get both speed and type checking, use `transpileOnly: true` together with [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin), which type checks in a separate process. -To output declaration files (.d.ts), set `"declaration": true` in your tsconfig. With `transpileOnly: false` (the default) they are emitted from the type-checked program. With `transpileOnly: true` they are only emitted if you also set [`"isolatedDeclarations": true`](https://www.typescriptlang.org/tsconfig/#isolatedDeclarations), which lets each file's declarations be generated without type-checking the whole project. +> **Note:** fork-ts-checker-webpack-plugin may not support TypeScript 7 yet. Check its documentation before relying on it with `ts-loader` v10. -If you use ts-loader with "transpileOnly": true along with [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin), you will need to configure fork-ts-checker-webpack-plugin to output definition files, you can learn more on the plugin's documentation page: https://github.com/TypeStrong/fork-ts-checker-webpack-plugin#typescript-options +### Sourcemaps -To output a built .d.ts file, you can use the [DeclarationBundlerPlugin](https://www.npmjs.com/package/types-webpack-bundler) in your webpack config. +To debug your original TypeScript in the browser: -### Failing the build on TypeScript compilation error +1. Set `"sourceMap": true` in your `tsconfig.json`. +2. Set webpack's [`devtool`](https://webpack.js.org/configuration/devtool/) option. Some good choices: + - `'inline-source-map'` - a good all-rounder; works well with karma-webpack. + - `'eval-cheap-module-source-map'` - fast rebuilds while developing. + - `'source-map'` - separate sourcemap files, typically for production. -The build **should** fail on TypeScript compilation errors. If it does not, check that you are not running webpack with an option that ignores errors, and that you have not filtered TypeScript errors out with [`ignoreDiagnostics`](#ignorediagnostics) or [`reportFiles`](#reportfiles). +### Using with Babel -For more background have a read of [this issue](https://github.com/TypeStrong/ts-loader/issues/108). +`ts-loader` works well with [babel-loader](https://github.com/babel/babel-loader). Chain them so that `ts-loader` runs first: `use: ['babel-loader', 'ts-loader']` (webpack applies loaders from right to left). ### `paths` module resolution -TypeScript's [`paths`](https://www.typescriptlang.org/tsconfig/#paths) option lets you import modules through aliases such as `@app/utils`. TypeScript does not rewrite those import specifiers in its output, so webpack also needs to know how to resolve them. +TypeScript's [`paths`](https://www.typescriptlang.org/tsconfig/#paths) option lets you import modules through aliases such as `@app/utils`. TypeScript doesn't rewrite these imports in its output, so webpack also needs to know how to resolve them. TypeScript 7 removed the `baseUrl` option, so each `paths` entry must be relative to the `tsconfig.json` it is declared in: @@ -243,134 +124,133 @@ TypeScript 7 removed the `baseUrl` option, so each `paths` entry must be relativ } ``` -If you are using webpack 5.105 or later, webpack can read `paths` from your `tsconfig.json` itself using the [`resolve.tsconfig`](https://webpack.js.org/configuration/resolve/#resolvetsconfig) option: +With webpack 5.105 or later, webpack can read `paths` from your `tsconfig.json` using [`resolve.tsconfig`](https://webpack.js.org/configuration/resolve/#resolvetsconfig): ```javascript module.exports = { - ... + // ... resolve: { tsconfig: true, // or a path, e.g. './path/to/tsconfig.json' - } - ... -} + }, +}; ``` -For webpack 4 or earlier versions of webpack 5, use the [tsconfig-paths-webpack-plugin](https://www.npmjs.com/package/tsconfig-paths-webpack-plugin) package (v4 or later, which supports `paths` without `baseUrl`). Use the config below or check the [package](https://github.com/dividab/tsconfig-paths-webpack-plugin/blob/master/README.md) for more information on usage. +With webpack 4 or older versions of webpack 5, use [tsconfig-paths-webpack-plugin](https://www.npmjs.com/package/tsconfig-paths-webpack-plugin) v4 or later: ```javascript const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin'); module.exports = { - ... + // ... resolve: { - plugins: [new TsconfigPathsPlugin({ configFile: "./path/to/tsconfig.json" })] - } - ... -} -``` - -### Options - -There are two types of options: TypeScript options (aka "compiler options") and loader options. TypeScript options should be set using a tsconfig.json file. Loader options can be specified through the `options` property in the webpack configuration: - -```javascript -module.exports = { - ... - module: { - rules: [ - { - test: /\.tsx?$/, - use: [ - { - loader: 'ts-loader', - options: { - transpileOnly: true - } - } - ] - } - ] - } -} + plugins: [ + new TsconfigPathsPlugin({ configFile: './path/to/tsconfig.json' }), + ], + }, +}; ``` -### Loader Options +### Declaration files (.d.ts) -#### transpileOnly +To output declaration files, set `"declaration": true` in your `tsconfig.json`. -| Type | Default Value | -| --------- | ------------- | -| `boolean` | `false` | +- With `transpileOnly: false` (the default), they are emitted from the type-checked program. +- With `transpileOnly: true`, they are only emitted if you also set [`"isolatedDeclarations": true`](https://www.typescriptlang.org/tsconfig/#isolatedDeclarations). If you use fork-ts-checker-webpack-plugin, you can [configure it](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin#typescript-options) to output declaration files instead. -If you want to speed up compilation significantly you can set this flag. -However, many of the benefits you get from static type checking between different dependencies in your application will be lost. +To bundle them into a single .d.ts file, you can use [DeclarationBundlerPlugin](https://www.npmjs.com/package/types-webpack-bundler). -It's advisable to use `transpileOnly` alongside the [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) to get full type checking again. (Note that fork-ts-checker-webpack-plugin may not support TypeScript 7 yet - see [Faster Builds](#faster-builds).) +### Code splitting and importing other files -> Tip: When you add the [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) to your webpack config, the `transpileOnly` will default to `true`, so you can skip that option. +Dynamic `import()` calls work as webpack [split points](https://webpack.js.org/guides/code-splitting/#dynamic-imports), so you can code split without any extra setup. -If you enable this option, webpack 4 will give you "export not found" warnings any time you re-export a type: +To import non-TypeScript files such as CSS, TypeScript needs a declaration for them. For example, add this to a `.d.ts` file in your project: -``` -WARNING in ./src/bar.ts -1:0-34 "export 'IFoo' was not found in './foo' - @ ./src/bar.ts - @ ./src/index.ts +```typescript +declare module '*.css'; ``` -The reason this happens is that when typescript doesn't do a full type check, it does not have enough information to determine whether an imported name is a type or not, so when the name is then exported, typescript has no choice but to emit the export. Fortunately, the extraneous export should not be harmful, so you can just suppress these warnings: +### Watch mode + +If TypeScript writes `.js` or `.d.ts` files into folders webpack is watching, webpack can rebuild in an endless loop. Tell webpack to ignore them: ```javascript -module.exports = { - ... - stats: { - warningsFilter: /export .* was not found in/ - } -} +// webpack 5 +plugins: [ + new webpack.WatchIgnorePlugin({ paths: [/\.js$/, /\.d\.[cm]?ts$/] }), +], + +// webpack 4 +plugins: [ + new webpack.WatchIgnorePlugin([/\.js$/, /\.d\.[cm]?ts$/]), +], ``` -#### resolveModuleName and resolveTypeReferenceDirective +### Hot Module Replacement -> **Note:** These options are accepted for backwards compatibility but currently have no effect. TypeScript's native API does not expose a custom module resolution hook. If it gains one, these options will work again; if it never does, they will be removed. +`ts-loader` doesn't officially support HMR. If you want to try it with `webpack-dev-server`, follow the [webpack HMR guide](https://webpack.js.org/guides/hot-module-replacement/), set [`transpileOnly`](#transpileonly) to `true`, and re-require the replaced module inside your HMR accept callback. -These options should be functions which will be used to resolve the import statements and the `` directives instead of the default TypeScript implementation. It's not intended that these will typically be used by a user of `ts-loader` - they exist to facilitate functionality such as [Yarn Plug’n’Play](https://yarnpkg.com/en/docs/pnp). +### The build doesn't fail on type errors -#### getCustomTransformers +It should. If it doesn't, check that you aren't running webpack with an option that ignores errors, and that you haven't filtered the errors out with [`ignoreDiagnostics`](#ignorediagnostics) or [`reportFiles`](#reportfiles). See [this issue](https://github.com/TypeStrong/ts-loader/issues/108) for more background. -| Type | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `string \| ((program: Program, getProgram: () => Program) => { before?: TransformerFactory[]; after?: TransformerFactory[]; afterDeclarations?: TransformerFactory[]; })` | +## Loader options -> **Note:** This option is accepted for backwards compatibility but currently has no effect. TypeScript's native API does not expose custom transformers. If it gains support, this option will work again; if it never does, it will be removed. +Most projects don't need any. TypeScript options belong in `tsconfig.json`; `ts-loader`'s own options go in the `options` property of the webpack rule: -Provide custom transformers, either as a function or as the path to a module exporting one. For example usage take a look at [typescript-plugin-styled-components](https://github.com/Igorbek/typescript-plugin-styled-components) or our [test](test/comparison-tests/customTransformer). +```javascript +module.exports = { + // ... + module: { + rules: [ + { + test: /\.([cm]?ts|tsx)$/, + loader: 'ts-loader', + options: { + transpileOnly: true, + }, + }, + ], + }, +}; +``` -#### logInfoToStdOut +#### transpileOnly | Type | Default Value | | --------- | ------------- | | `boolean` | `false` | -Writes `ts-loader`'s own info messages (see [`logLevel`](#loglevel)) to stdout instead of stderr. The default keeps stdout clean, so you can read webpack's own output from it, e.g. via pipes or `webpack --json`. +Skips type checking, which makes compilation much faster. You lose type errors, so consider pairing it with fork-ts-checker-webpack-plugin (see [Faster builds](#faster-builds)). When you add fork-ts-checker-webpack-plugin to your webpack config, `transpileOnly` defaults to `true`. -#### logLevel +With webpack 4, this option causes "export not found" warnings when you re-export a type: -| Type | Default Value | -| -------- | ------------- | -| `string` | `warn` | +``` +WARNING in ./src/bar.ts +1:0-34 "export 'IFoo' was not found in './foo' +``` -Can be `info`, `warn` or `error`. `ts-loader`'s only console output is a couple of info messages (which TypeScript API and `tsconfig.json` it is using, and a notice if the compiler process fails to shut down cleanly): `info` shows them, while `warn` and `error` both hide them. They go to stderr unless [`logInfoToStdOut`](#loginfotostdout) is `true`. +Without a full type check, TypeScript can't tell whether an imported name is a type, so it keeps the export. The extra export is harmless, so you can hide these warnings: -TypeScript errors and warnings are not affected by this option - they are always reported through webpack. +```javascript +module.exports = { + // ... + stats: { + warningsFilter: /export .* was not found in/, + }, +}; +``` -#### silent +#### configFile -| Type | Default Value | -| --------- | ------------- | -| `boolean` | `false` | +| Type | Default Value | +| -------- | ----------------- | +| `string` | `'tsconfig.json'` | -If `true`, no console.log messages will be emitted. Note that most error -messages are emitted via webpack which is not affected by this flag. +Where to find your TypeScript config. This can be: + +- a file name. `ts-loader` looks for it in the entry file's folder, then in each parent folder. +- a relative path, resolved relative to the entry file. +- an absolute path. #### ignoreDiagnostics @@ -378,8 +258,7 @@ messages are emitted via webpack which is not affected by this flag. | ---------- | ------------- | | `number[]` | `[]` | -You can squelch certain TypeScript errors by specifying an array of diagnostic -codes to ignore. +TypeScript error codes to ignore, e.g. `[2307]`. #### reportFiles @@ -387,50 +266,48 @@ codes to ignore. | ---------- | ------------- | | `string[]` | `[]` | -Only report errors on files matching these glob patterns. +Only report errors in files matching these glob patterns. Useful when some type definitions have errors that don't affect your app. ```javascript - // in webpack.config.js - { - test: /\.ts$/, - loader: 'ts-loader', - options: { reportFiles: ['src/**/*.{ts,tsx}', '!src/skip.ts'] } - } +options: { + reportFiles: ['src/**/*.{ts,tsx}', '!src/skip.ts']; +} ``` -This can be useful when certain types definitions have errors that are not fatal to your application. - -#### configFile - -| Type | Default Value | -| -------- | ----------------- | -| `string` | `'tsconfig.json'` | - -Allows you to specify where to find the TypeScript configuration file. +#### appendTsSuffixTo / appendTsxSuffixTo -You may provide - -- just a file name. The loader then will search for the config file of each entry point in the respective entry point's containing folder. If a config file cannot be found there, it will travel up the parent directory chain and look for the config file in those folders. -- a relative path to the configuration file. It will be resolved relative to the respective `.ts` entry file. -- an absolute path to the configuration file. - -#### compiler - -| Type | Default Value | -| -------- | -------------- | -| `string` | `'typescript'` | +| Type | Default Value | +| ---------------------- | ------------- | +| `(RegExp \| string)[]` | `[]` | -Allows you to use a TypeScript package other than the one installed as `typescript`, such as a fork or a specific prerelease installed under an alias. +Patterns (regular expressions, or strings treated as regular expressions) matched against each file name. When a file name matches, `.ts` (or `.tsx`) is appended to it, so TypeScript treats the file as TypeScript whatever its extension. -The package must expose TypeScript's native API at a `/sync` entry point (for example `typescript/sync`). Packages that only provide the classic compiler API, such as `ttypescript`, are not supported. +This is useful for single-file components such as [Vue](https://vuejs.org/guide/scaling-up/sfc.html), whose `