ts-checker-rspack-plugin

Rspack plugin that runs TypeScript type checker on a separate process.

Credits

This plugin is forked from TypeStrong/fork-ts-checker-webpack-plugin, which is created by Piotr Oleś. See the original project's LICENSE.

Big thanks to fork-ts-checker-webpack-plugin creators and contributors for their great work. ❤️

Features

• Speeds up TypeScript type checking (by moving it to a separate process) 🏎
• Supports modern TypeScript features like project references and incremental mode ✨
• Displays nice error messages with the code frame formatter 🌈

💡 For Rsbuild projects, use @rsbuild/plugin-type-check to get out-of-the-box experience.

Installation

This plugin requires Node.js >=16.0.0+, Rspack ^1.0.0, TypeScript ^3.8.0

# with npm
npm install -D ts-checker-rspack-plugin

# with yarn
yarn add -D ts-checker-rspack-plugin

# with pnpm
pnpm add -D ts-checker-rspack-plugin

The minimal Rspack config with builtin:swc-loader.

// rspack.config.mjs
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',
            },
          },
        },
      },
    ],
  },
  plugins: [new TsCheckerRspackPlugin()],
};

If you are using CommonJS:

// rspack.config.js
const { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin');

module.exports = {
  plugins: [new TsCheckerRspackPlugin()],
};

Modules resolution

It's very important to be aware that this plugin uses TypeScript's, not Rspack's modules resolution. It means that you have to setup tsconfig.json correctly.

It's because of the performance - with TypeScript's module resolution we don't have to wait for Rspack to compile files.

To debug TypeScript's modules resolution, you can use tsc --traceResolution command.

Options

TypeScript options

Options for the TypeScript checker (typescript option object).

Issues options

Options for the issues filtering (issue option object). I could write some plain text explanation of these options but I think code will explain it better:

interface Issue {
  severity: 'error' | 'warning';
  code: string;
  file?: string;
}

type IssueMatch = Partial<Issue>; // file field supports glob matching
type IssuePredicate = (issue: Issue) => boolean;
type IssueFilter = IssueMatch | IssuePredicate | (IssueMatch | IssuePredicate)[];

Plugin hooks

This plugin provides some custom Rspack hooks:

To access plugin hooks and tap into the event, we need to use the getCompilerHooks static method. When we call this method with a Rspack compiler instance, it returns the object with tapable hooks where you can pass in your callbacks.

// ./src/rspack/MyRspackPlugin.js
const { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin');

class MyRspackPlugin {
  apply(compiler) {
    const hooks = TsCheckerRspackPlugin.getCompilerHooks(compiler);

    // log some message on waiting
    hooks.waiting.tap('MyPlugin', () => {
      console.log('waiting for issues');
    });
    // don't show warnings
    hooks.issues.tap('MyPlugin', (issues) => issues.filter((issue) => issue.severity === 'error'));
  }
}

module.exports = MyRspackPlugin;

// rspack.config.js
const { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin');
const MyRspackPlugin = require('./src/rspack/MyRspackPlugin');

module.exports = {
  /* ... */
  plugins: [new TsCheckerRspackPlugin(), new MyRspackPlugin()],
};

Profiling types resolution

When using TypeScript 4.3.0 or newer you can profile long type checks by setting "generateTrace" compiler option. This is an instruction from microsoft/TypeScript#40063:

1. Set "generateTrace": "{folderName}" in your tsconfig.json (under compilerOptions)
2. Look in the resulting folder. If you used build mode, there will be a legend.json telling you what went where. Otherwise, there will be trace.json file and types.json files.
3. Navigate to edge://tracing or chrome://tracing and load trace.json
4. Expand Process 1 with the little triangle in the left sidebar
5. Click on different blocks to see their payloads in the bottom pane
6. Open types.json in an editor
7. When you see a type ID in the tracing output, go-to-line {id} to find data about that type

Enabling incremental mode

You must both set "incremental": true in your tsconfig.json (under compilerOptions) and also specify mode: 'write-references' in TsCheckerRspackPlugin settings.

License

MIT License