\n\nRspack plugin that runs TypeScript type checker on a separate process.\n\n## Features\n\n- Speeds up [TypeScript](https://github.com/Microsoft/TypeScript) type checking (by moving it to a separate process) 🏎\n- Supports modern TypeScript features like\n [project references](https://www.typescriptlang.org/docs/handbook/project-references.html) and\n [incremental mode](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#faster-subsequent-builds-with-the---incremental-flag) ✨\n- Displays nice error messages with the [code frame](https://babeljs.io/docs/en/next/babel-code-frame.html) formatter 🌈\n\n💡 For Rsbuild projects, use [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check)\nto get out-of-the-box experience.\n\n## Installation\n\nThis plugin requires **Rspack ^1.0.0**, **TypeScript ^3.8.0**\n\n```sh\n# with pnpm\npnpm add -D ts-checker-rspack-plugin\n\n# with npm\nnpm install -D ts-checker-rspack-plugin\n\n# with yarn\nyarn add -D ts-checker-rspack-plugin\n```\n\nThe minimal Rspack config with [builtin:swc-loader](https://rspack.rs/guide/features/builtin-swc-loader).\n\n```js\n// rspack.config.mjs\nimport { TsCheckerRspackPlugin } from 'ts-checker-rspack-plugin';\n\nexport default {\n entry: './src/index.ts',\n resolve: {\n extensions: ['.ts', '.tsx', '.js'],\n },\n module: {\n rules: [\n {\n test: /\\.tsx?$/,\n loader: 'builtin:swc-loader',\n options: {\n detectSyntax: 'auto',\n },\n },\n ],\n },\n plugins: [new TsCheckerRspackPlugin()],\n};\n```\n\nIf you are using CommonJS:\n\n```js\n// rspack.config.js\nconst { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin');\n\nmodule.exports = {\n plugins: [new TsCheckerRspackPlugin()],\n};\n```\n\n## Modules resolution\n\nIt's very important to be aware that **this plugin uses [TypeScript](https://github.com/Microsoft/TypeScript)'s, not\nRspack's modules resolution**. It means that you have to setup `tsconfig.json` correctly.\n\n> It's because of the performance - with TypeScript's module resolution we don't have to wait for Rspack to compile files.\n>\n> To debug TypeScript's modules resolution, you can use `tsc --traceResolution` command.\n\n## TypeScript 7+ support\n\n[`typescript.tsgo`](#tsgo) uses the native checker included in TypeScript >= 7. It can reduce type-checking time on large projects.\n\nWhen the configured or default installed `typescript` package is major version 7 or higher, the plugin enables `typescript.tsgo` automatically and runs the native executable from that package.\n\nThe default package detection uses [`typescript.resolveRoot`](#resolveroot) when it is set.\n\nWhen `typescript.tsgo: true` is set without a custom [`typescriptPath`](#typescriptpath) and TypeScript 7+ is not installed, the plugin falls back to `@typescript/native-preview` for compatibility.\n\nIf the checker output cannot be parsed safely, the raw output is printed and the build fails when it exits with errors.\n\nSupported options include:\n\n- [`typescript.configFile`](#configfile)\n- [`typescript.context`](#context)\n- [`typescript.build`](#build)\n- `typescript.resolveRoot`\n- `typescript.typescriptPath`\n- [`async`](#async)\n- [`logger`](#logger)\n\nIt also supports `tsconfig.json` compiler options used by `tsgo`,\nincluding `incremental` and `composite`.\n\nInstall TypeScript >= 7.0.0 to enable `tsgo` automatically:\n\n```sh\n# with npm\nnpm install -D typescript@latest\n\n# with yarn\nyarn add -D typescript@latest\n\n# with pnpm\npnpm add -D typescript@latest\n```\n\n> The `@typescript/native-preview` path is kept only for compatibility. New setups should use TypeScript 7+ from the standard `typescript` package.\n\nLimitations:\n\n- [`issue.include`](#include), [`issue.exclude`](#exclude), and [`issue.defaultSeverity`](#defaultseverity) only apply to diagnostics whose checker output can be matched by `file`, `line`, `column`, `code`, and `message`.\n- [`typescript.configOverwrite`](#configoverwrite), [`typescript.diagnosticOptions`](#diagnosticoptions), and [`typescript.profile`](#profile) are not supported.\n- TypeScript API-based formatting or filesystem output rewrites are not supported.\n- Plugin-controlled declaration or reference emit modes such as `write-dts` and `write-references` are not supported. `tsgo` always runs with `--noEmit`.\n- This integration may change when TypeScript provides a stable JavaScript API for the native checker.\n\n## Options\n\n### async\n\nControls whether type checking blocks watch mode compilation.\n\n- When `true`, issues are reported after Rspack finishes compiling.\n- When `false`, issues are added to the compilation before it finishes.\n\nUsed only in the watch mode.\n\n- **Type:** `boolean`\n- **Default:** `compiler.options.mode === 'development'`\n- **Example:**\n\nBlock watch mode compilation until type checking finishes:\n\n```js\nnew TsCheckerRspackPlugin({\n async: false,\n});\n```\n\n### typescript\n\nOptions passed to the TypeScript checker.\n\nSee [TypeScript options](#typescript-options).\n\n- **Type:** `object`\n- **Default:** `{}`\n- **Example:**\n\nUse a separate TypeScript config for type checking:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n configFile: './tsconfig.build.json',\n },\n});\n```\n\n### issue\n\nOptions for filtering emitted issues and overriding their severity.\n\nSee [Issues options](#issues-options).\n\n- **Type:** `object`\n- **Default:** `{}`\n- **Example:**\n\nOnly report issues from the `src` directory:\n\n```js\nnew TsCheckerRspackPlugin({\n issue: {\n include: [{ file: '**/src/**/*' }],\n },\n});\n```\n\n### formatter\n\nControls how issues are formatted in terminal output and Rspack errors.\n\nAvailable formatters are `basic`, `codeframe` and a custom `function`.\n\n- **Type:** `string` or `object` or `function`\n- **Default:** `codeframe`\n- **Example:**\n\nUse the basic formatter:\n\n```js\nnew TsCheckerRspackPlugin({\n formatter: 'basic',\n});\n```\n\nTo [configure](https://babeljs.io/docs/en/babel-code-frame#options) `codeframe` formatter,\npass: `{ type: 'codeframe', options: { } }`.\n\nTo use absolute file path, pass: `{ type: 'codeframe', pathType: 'absolute' }`.\n\n### logger\n\nConsole-like object used to print async-mode progress, statistics and formatted issues.\n\nUse `webpack-infrastructure` to print through Rspack's infrastructure logger.\n\n- **Type:** `{ log: function, error: function }` or `webpack-infrastructure`\n- **Default:** `console`\n- **Example:**\n\nUse a custom logger object:\n\n```js\nnew TsCheckerRspackPlugin({\n logger: {\n log(message) {\n console.log(message);\n },\n error(message) {\n console.error(message);\n },\n },\n});\n```\n\n### devServer\n\nControls whether async mode issues are sent to the dev server error overlay.\n\nWhen `false`, issues are still logged but are not injected into the overlay.\n\n- **Type:** `boolean`\n- **Default:** `true`\n- **Example:**\n\nDisable the dev server error overlay integration:\n\n```js\nnew TsCheckerRspackPlugin({\n devServer: false,\n});\n```\n\n## TypeScript options\n\nOptions for the TypeScript checker (`typescript` option object).\n\n### memoryLimit\n\nMemory limit for the checker worker process in MB.\n\nIf the process exits with an allocation error, try to increase this number.\n\n- **Type:** `number`\n- **Default:** `8192`\n- **Example:**\n\nLimit the checker process to 4096 MB:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n memoryLimit: 4096,\n },\n});\n```\n\n### configFile\n\nPath to the TypeScript config file.\n\nRelative paths are resolved from `compiler.options.context`.\n\n- **Type:** `string`\n- **Default:** `'tsconfig.json'`\n- **Example:**\n\nUse a non-default TypeScript config file:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n configFile: './tsconfig.build.json',\n },\n});\n```\n\n### configOverwrite\n\nConfiguration merged into the loaded `tsconfig.json`.\n\nThe checker applies implicit compiler option overrides first, then merges this object.\n\nSupported fields are: `extends`, `compilerOptions`, `include`, `exclude`, `files`, and `references`.\n\n- **Type:** `object`\n- **Default:** `{}`\n- **Example:**\n\nCheck only files under `src`:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n configOverwrite: {\n include: ['src'],\n },\n },\n});\n```\n\n### context\n\nBase path used when parsing files, include, exclude and references from the TypeScript config.\n\nUseful if you want to keep your `tsconfig.json` in an external package.\n\nKeep in mind that **not** having a `tsconfig.json` in your project root can cause different behavior between `ts-checker-rspack-plugin` and `tsc`.\n\nWhen using editors like `VS Code` it is advised to add a `tsconfig.json` file to the root of the project and extend the config file referenced in option `configFile`.\n\n- **Type:** `string`\n- **Default:** `dirname(configuration.configFile)`\n- **Example:**\n\nResolve config file entries from the current package root:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n configFile: './config/tsconfig.json',\n context: import.meta.dirname,\n },\n});\n```\n\n### build\n\nRuns TypeScript in project build mode, equivalent to `tsc --build`.\n\n- **Type:** `boolean`\n- **Default:** `false`\n- **Example:**\n\nEnable TypeScript build mode:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n build: true,\n },\n});\n```\n\n### mode\n\nControls which TypeScript output artifacts the plugin is allowed to write to disk：\n\n- `readonly` if you don't want to write anything on the disk\n- `write-dts` to write only `.d.ts` files\n- `write-tsbuildinfo` to write only `.tsbuildinfo` files\n- `write-references` to write both `.js` and `.d.ts` files of project references\n\n`write-tsbuildinfo` and `write-references` require `build: true`.\n\n- **Type:** `'readonly'` or `'write-dts'` or `'write-tsbuildinfo'` or `'write-references'`\n- **Default:** `build === true ? 'write-tsbuildinfo' : 'readonly'`\n- **Example:**\n\nWrite only `.tsbuildinfo` files in build mode:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n build: true,\n mode: 'write-tsbuildinfo',\n },\n});\n```\n\n### diagnosticOptions\n\nSelects which TypeScript diagnostic categories the checker collects.\n\n- **Type:** `object`\n- **Default:** `{ syntactic: false, semantic: true, declaration: false, global: false }`\n- **Example:**\n\nEnable syntactic diagnostics in addition to semantic diagnostics:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n diagnosticOptions: {\n syntactic: true,\n semantic: true,\n },\n },\n});\n```\n\n### profile\n\nEnables TypeScript performance measurements and prints them as a table.\n\n- **Type:** `boolean`\n- **Default:** `false`\n- **Example:**\n\nPrint TypeScript performance timings:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n profile: true,\n },\n});\n```\n\n### resolveRoot\n\nDirectory used to resolve the default TypeScript package.\n\nRelative paths are resolved from `compiler.options.context`. Only used when `typescriptPath` is not set.\n\n- **Type:** `string`\n- **Default:** `undefined`\n- **Example:**\n\nResolve TypeScript from the current package root:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n resolveRoot: import.meta.dirname,\n },\n});\n```\n\n### typescriptPath\n\nCustom TypeScript path.\n\n- Without `tsgo`, point to the TypeScript package entry.\n- In `tsgo` mode, use an absolute path to the TypeScript 7+ `package.json`\n\n- **Type:** `string`\n- **Default:**\n - `require.resolve('typescript/package.json')` for TypeScript 7+\n - otherwise `require.resolve('typescript')`\n- **Example:**\n\nUse the installed `typescript` package with the JavaScript checker:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n tsgo: false,\n typescriptPath: require.resolve('typescript'),\n },\n});\n```\n\n### tsgo\n\nEnables the native TypeScript checker.\n\nWhen unset, the plugin enables it automatically when TypeScript 7+ is detected.\n\n- **Type:** `boolean`\n- **Default:** `true` when TypeScript 7+ is detected, otherwise `false`\n- **Example:**\n\nForce the native checker on:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n tsgo: true,\n },\n});\n```\n\n## Issues options\n\nOptions for the issues filtering (`issue` option object).\n\n- **Type**:\n\n```typescript\ninterface IssueOptions {\n include?: IssuePredicateOption;\n exclude?: IssuePredicateOption;\n defaultSeverity?: 'auto' | 'warning' | 'error';\n}\n\ninterface Issue {\n severity: 'error' | 'warning';\n code: string;\n // file field supports glob matching\n file?: string;\n}\n\ntype IssueMatch = Partial;\ntype IssuePredicate = (issue: Issue) => boolean;\ntype IssuePredicateOption = IssuePredicate | IssueMatch | (IssuePredicate | IssueMatch)[];\n```\n\n### include\n\nLimits reported issues to those matching the provided issue match object or predicate.\n\n- If `object`, defines issue properties that should be [matched](src/issue/issue-match.ts).\n- If `function`, acts as a predicate where `issue` is an argument.\n\n- **Type:** `IssueFilter`\n- **Default:** `undefined`\n- **Example:**\n\nOnly report issues from the `src` directory:\n\n```js\nnew TsCheckerRspackPlugin({\n issue: {\n include: [{ file: '**/src/**/*' }],\n },\n});\n```\n\n### exclude\n\nExcludes issues matching the provided issue match object or predicate.\n\n- **Type:** `IssueFilter`\n- **Default:** `undefined`\n- **Example:**\n\nExclude issues from `.spec.ts` files:\n\n```js\nnew TsCheckerRspackPlugin({\n issue: {\n exclude: [{ file: '**/*.spec.ts' }],\n },\n});\n```\n\n### defaultSeverity\n\nControls how the plugin assigns the severity of emitted issues.\n\n- **Type:** `'auto' | 'warning' | 'error'`\n- **Default:** `'auto'`\n\n`defaultSeverity` behavior:\n\n- `auto`: Uses the default mapping based on the TypeScript diagnostic category (`Error` → `error`, `Warning` → `warning`).\n- `warning`: Forces all issues to be emitted as warnings.\n- `error`: Forces all issues to be emitted as errors.\n\n- **Example:**\n\nForce all issues to be emitted as warnings and do not break the build:\n\n```js\nnew TsCheckerRspackPlugin({\n issue: {\n defaultSeverity: 'warning',\n },\n});\n```\n\n## Plugin hooks\n\nThis plugin provides some custom Rspack hooks:\n\n| Hook key | Type | Params | Description |\n| ---------- | -------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `start` | `AsyncSeriesWaterfallHook` | `change, compilation` | Starts issues checking for a compilation. It's an async waterfall hook, so you can modify the list of changed and removed files or delay the start of the service. |\n| `waiting` | `SyncHook` | `compilation` | Waiting for the issues checking. |\n| `canceled` | `SyncHook` | `compilation` | Issues checking for the compilation has been canceled. |\n| `error` | `SyncHook` | `compilation` | An error occurred during issues checking. |\n| `issues` | `SyncWaterfallHook` | `issues, compilation` | Issues have been received and will be reported. It's a waterfall hook, so you can modify the list of received issues. |\n\nTo access plugin hooks and tap into the event, we need to use the `getCompilerHooks` static method.\nWhen we call this method with a [Rspack compiler instance](https://rspack.rs/api/javascript-api/compiler), it returns the object with\n[tapable](https://github.com/webpack/tapable) hooks where you can pass in your callbacks.\n\n```js\n// ./src/rspack/MyRspackPlugin.js\nconst { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin');\n\nclass MyRspackPlugin {\n apply(compiler) {\n const hooks = TsCheckerRspackPlugin.getCompilerHooks(compiler);\n\n // log some message on waiting\n hooks.waiting.tap('MyPlugin', () => {\n console.log('waiting for issues');\n });\n // don't show warnings\n hooks.issues.tap('MyPlugin', (issues) => issues.filter((issue) => issue.severity === 'error'));\n }\n}\n\nmodule.exports = MyRspackPlugin;\n\n// rspack.config.js\nconst { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin');\nconst MyRspackPlugin = require('./src/rspack/MyRspackPlugin');\n\nmodule.exports = {\n /* ... */\n plugins: [new TsCheckerRspackPlugin(), new MyRspackPlugin()],\n};\n```\n\n## Profiling types resolution\n\nWhen using TypeScript 4.3.0 or newer you can profile long type checks by setting \"generateTrace\" compiler option.\n\nThis is an instruction from [microsoft/TypeScript#40063](https://github.com/microsoft/TypeScript/pull/40063):\n\n1. Set \"generateTrace\": \"{folderName}\" in your `tsconfig.json` (under `compilerOptions`)\n2. Look in the resulting folder. If you used build mode, there will be a `legend.json` telling you what went where.\n Otherwise, there will be `trace.json` file and `types.json` files.\n3. Navigate to [edge://tracing](edge://tracing) or [chrome://tracing](chrome://tracing) and load `trace.json`\n4. Expand Process 1 with the little triangle in the left sidebar\n5. Click on different blocks to see their payloads in the bottom pane\n6. Open `types.json` in an editor\n7. When you see a type ID in the tracing output, go-to-line {id} to find data about that type\n\n## Performance optimization\n\nThis plugin delegates type checking to TypeScript, so overall performance is mostly determined by `tsc` itself.\n\nIf you need faster type checks, start by optimizing your TypeScript setup using the [official TypeScript performance guide](https://github.com/microsoft/TypeScript/wiki/Performance).\n\nFor example, properly configuring the `include` and `exclude` scopes in `tsconfig.json` can significantly reduce unnecessary type checking and improve TypeScript performance:\n\n```json title=\"tsconfig.json\"\n{\n \"include\": [\"src\"],\n \"exclude\": [\"**/node_modules\", \"**/.*/\"]\n}\n```\n\n## Enabling incremental mode\n\nTypeScript's \"incremental\" mode speeds up initial cold-start typechecks keeping an on-disk cache.\n\nIt does not speed up subsequent subsequent re-typechecking during the runtime of the dev server.\n\nTo enable incremental mode, set `\"compilerOptions.incremental\": true` in your `tsconfig.json`:\n\n```diff\n{\n \"compilerOptions\": {\n+ \"incremental\": true,\n }\n}\n```\n\nIn the past we also recommended to combine incremental mode with specifying `build: true` in `TsCheckerRspackPlugin` settings to enable TypeScript's [\"Build\" mode](https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript) designed to handle [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript).\n\nHowever, \"Build\" mode causes significant slowdowns for re-typechecks when the dev server is already running, as it switches from TypeScript's in-memory \"Watch\" mode to \"Build\" mode. If you need \"Build\" mode, it can be configured as:\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n build: true,\n },\n});\n```\n\n## Vue components\n\nTo enable typecheck in `.vue` files, use the custom TypeScript wrapper [`@esctn/vue-tsc-api`](https://www.npmjs.com/package/@esctn/vue-tsc-api). It works on top of [`vue-tsc`](https://www.npmjs.com/package/vue-tsc) — a popular CLI tool for type-checking Vue 3 code.\n\n```bash\nnpm add @esctn/vue-tsc-api -D\n```\n\n```js\nnew TsCheckerRspackPlugin({\n typescript: {\n typescriptPath: '@esctn/vue-tsc-api',\n },\n});\n```\n\n## Credits\n\nThis plugin is forked from [TypeStrong/fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin),\nwhich is created by [Piotr Oleś](https://github.com/piotr-oles).\nSee the original project's [LICENSE](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/blob/main/LICENSE).\n\nBig thanks to `fork-ts-checker-webpack-plugin` creators and contributors for their great work. ❤️\n\n## License\n\nMIT License\n","readmeFilename":""}
![\"npm](\"https://img.shields.io/npm/v/ts-checker-rspack-plugin?style=flat-square&colorA=564341&colorB=EDED91\")
\n \n ![\"license\"](\"https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square&colorA=564341&colorB=EDED91\"){kind=icon}
\n ![\"downloads\"](\"https://img.shields.io/npm/dm/ts-checker-rspack-plugin.svg?style=flat-square&colorA=564341&colorB=EDED91\")
\n