Rspack TypeScript Checker Plugin

Common errors

• ERROR in <file>: Cannot find name 'MyComponentProps'.

  cause TypeScript is unable to resolve types or modules, often due to a misconfigured `tsconfig.json` that doesn't align with the project structure or uses incorrect path mappings.
  fix Verify your `tsconfig.json` settings, specifically `baseUrl`, `paths`, `include`, and `exclude`. The plugin relies on TypeScript's own resolution, not Rspack's. Run `tsc --traceResolution` to debug TypeScript's module resolution.

• TypeError: TsCheckerRspackPlugin is not a constructor

  cause Attempting to use `new TsCheckerRspackPlugin()` without correctly importing the named export. This often happens when mixing CommonJS `require` with `import` syntax or incorrect destructuring.
  fix For ES Modules, ensure `import { TsCheckerRspackPlugin } from 'ts-checker-rspack-plugin';` is used. For CommonJS, use `const { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin');`.

• Rspack build finishes without type errors, but 'tsc --noEmit' reports errors.

  cause The plugin's configuration (or the `tsconfig.json` it uses) might not be checking all necessary files or directories, leading to a discrepancy between the plugin's output and a direct `tsc` run.
  fix Ensure the `tsconfig.json` file specified for the plugin via `typescript.configFile` (if any) and its `include`/`exclude` options cover all your source files. Double-check that `tsconfig.json` is consistent between your Rspack configuration and standalone `tsc` commands.

Warnings

• breaking The plugin updated its peer dependency to officially support `@rspack/core` v2. Users upgrading Rspack to v2 should update ts-checker-rspack-plugin to v1.2.4 or newer to ensure compatibility and correct behavior.
  Fix: Upgrade `ts-checker-rspack-plugin` to version `1.2.4` or higher. Ensure your `@rspack/core` version matches `^1.0.0 || ^2.0.0-0`.
• gotcha This plugin utilizes TypeScript's internal module resolution logic, not Rspack's. Incorrect `tsconfig.json` configurations for paths or includes can lead to missing type errors or slow performance, even if Rspack's module resolution is correctly set up.
  Fix: Carefully configure your `tsconfig.json` (especially `baseUrl`, `paths`, `include`, and `exclude`). Use `tsc --traceResolution` to debug TypeScript's module resolution when issues arise.
• deprecated As of v1.2.4, the README no longer recommends TypeScript's 'Build mode' (`--build` or `incremental`) for incremental builds directly with this plugin, suggesting that other approaches might be more performant or reliable.
  Fix: Review the plugin's documentation on performance optimization and incremental mode. Consider alternative strategies for faster rebuilds if previously relying solely on TypeScript's build mode. For Rsbuild projects, consider `@rsbuild/plugin-type-check`.
• breaking Versions prior to `1.1.7` could lead to an infinite rebuild loop due to incorrect output path exclusion, severely impacting build performance and stability.
  Fix: Upgrade `ts-checker-rspack-plugin` to version `1.1.7` or newer to ensure the fix is applied and prevent rebuild loops by correctly excluding output paths.
• gotcha The plugin requires Node.js version 16.0.0 or higher. Using an older Node.js version will result in errors or unexpected behavior during installation or execution.
  Fix: Ensure your development environment and CI/CD pipelines are using Node.js version 16.0.0 or newer. Update Node.js if necessary.

Install

• npm install ts-checker-rspack-plugin npm
• yarn add ts-checker-rspack-plugin yarn
• pnpm add ts-checker-rspack-plugin pnpm

Imports

• TsCheckerRspackPlugin
  wrong:

  import TsCheckerRspackPlugin from 'ts-checker-rspack-plugin';

  correct:

  import { TsCheckerRspackPlugin } from 'ts-checker-rspack-plugin';

  The plugin class is a named export, not a default export. Ensure you use curly braces for import.
• TsCheckerRspackPlugin (CommonJS)
  wrong:

  const TsCheckerRspackPlugin = require('ts-checker-rspack-plugin');

  correct:

  const { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin');

  When using CommonJS, the plugin is a named export requiring destructuring from the `require` call.
• Plugin options type (example)

  import type { Options } from 'ts-checker-rspack-plugin';

  While not explicitly shown in the README, for advanced TypeScript usage, you might import the `Options` type to get IntelliSense for plugin configuration.

Quickstart

This quickstart demonstrates a minimal Rspack configuration integrating the ts-checker-rspack-plugin for TypeScript type checking with SWC loader, showing both basic setup and common configurations like tsconfig path and async mode.

import { TsCheckerRspackPlugin } from 'ts-checker-rspack-plugin';

export default {
  entry: './src/index.ts',
  resolve: {
    extensions: ['.ts', '.tsx', '.js'],
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: 'typescript',
              tsx: true // Enable TSX parsing if you're using React/Preact with TypeScript
            },
            transform: {
                react: {
                    runtime: 'automatic'
                }
            }
          },
          // Optional: specify target environment for SWC to match your project's browserlist/targets
          env: {
            targets: ['chrome 90', 'safari 15', 'firefox 90']
          }
        },
      },
    ],
  },
  plugins: [
    new TsCheckerRspackPlugin({
      // Optional: specify your tsconfig.json file path if it's not at the root
      typescript: {
        configFile: './tsconfig.json'
      },
      // Optional: Enable async mode for non-blocking type checking (default is false)
      async: false
    })
  ],
  // Performance optimization: prevent the plugin from infinitely rebuilding
  output: {
    path: './dist'
  }
};