TypeScript Checker

TypeScript type checking integration using the built-in TypeScript compiler, providing real-time type checking in development and build-time validation.

Capabilities

TypeScript Configuration

Enable and configure TypeScript type checking with flexible options for development and build modes.

/**
 * TypeScript checker configuration
 * - Set to `true` to enable type checking with default configuration
 * - Set to `false` to disable type checking
 * - Provide partial options object for custom configuration
 */
type TscConfig = boolean | Partial<TsConfigOptions>;

interface TsConfigOptions {
  /** Path to tsconfig.json file */
  tsconfigPath: string;
  
  /** Path to typescript package */
  typescriptPath: string;
  
  /** Root path of current working directory */
  root: string;
  
  /** Enable build mode flag */
  buildMode: boolean;
}

Usage Examples:

// Simple enable with defaults
checker({
  typescript: true,
});

// Custom tsconfig path
checker({
  typescript: {
    tsconfigPath: './tsconfig.build.json',
  },
});

// Full custom configuration
checker({
  typescript: {
    tsconfigPath: './tsconfig.json',
    typescriptPath: require.resolve('typescript'),
    root: process.cwd(),
    buildMode: false,
  },
});

Default Configuration

When typescript: true is used, the following default configuration is applied:

{
  tsconfigPath: 'tsconfig.json',        // Look for tsconfig.json in project root
  typescriptPath: 'typescript',         // Use typescript from node_modules
  root: process.cwd(),                  // Use current working directory
  buildMode: false,                     // Enable incremental checking in dev mode
}

Development Mode Behavior

In development mode, the TypeScript checker:

• Runs in a separate worker thread to avoid blocking the development server
• Performs incremental type checking for faster subsequent checks
• Reports type errors via the error overlay system
• Watches for file changes and re-runs type checking automatically
• Integrates with Vite's hot module replacement (HMR) system

Build Mode Behavior

In build mode, the TypeScript checker:

• Runs the TypeScript compiler as a separate process
• Uses the configured tsconfigPath for type checking
• Exits the build process with non-zero exit code if type errors are found
• Can be disabled by setting enableBuild: false in shared configuration
• Supports vite build --watch mode without terminating the process

Integration with TSConfig

The checker respects your TypeScript configuration:

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    // ... other TypeScript options
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

The checker will use these settings when performing type checking.

Error Reporting

TypeScript errors are reported with detailed information:

• File location: Exact file path and line/column numbers
• Error message: TypeScript compiler error message
• Code frame: Highlighted code snippet showing the error context
• Error code: TypeScript error code (e.g., TS2322)

Advanced Configuration

For complex projects, you can configure multiple aspects:

checker({
  typescript: {
    // Use different tsconfig for development
    tsconfigPath: process.env.NODE_ENV === 'development' 
      ? './tsconfig.dev.json' 
      : './tsconfig.json',
    
    // Use specific TypeScript version
    typescriptPath: require.resolve('typescript/lib/typescript.js'),
    
    // Set root directory
    root: './packages/frontend',
    
    // Enable build mode optimizations
    buildMode: process.env.NODE_ENV === 'production',
  },
});

Performance Tips

• Use "incremental": true in your tsconfig.json for faster subsequent type checks
• Consider using TypeScript project references for monorepo setups
• Exclude test files and node_modules in your tsconfig.json
• Use "skipLibCheck": true to skip type checking of declaration files if build performance is critical

Troubleshooting

Common issues and solutions:

TypeScript not found: Ensure TypeScript is installed as a dependency

npm install --save-dev typescript

Custom TypeScript version: Specify the exact path to the TypeScript package

typescript: {
  typescriptPath: require.resolve('typescript'),
}

Different tsconfig for development: Use separate configuration files

typescript: {
  tsconfigPath: './tsconfig.dev.json',
}