TypeScript Configuration

/**
 * TypeScript worker configuration options
 */
interface TypeScriptWorkerOptions {
  /**
   * Memory limit for the TypeScript worker process in MB
   * Helps prevent out-of-memory errors on large codebases
   */
  memoryLimit?: number;
  
  /**
   * Path to TypeScript configuration file
   * Defaults to tsconfig.json in context directory
   */
  configFile?: string;
  
  /**
   * Configuration overrides to apply on top of tsconfig.json
   */
  configOverwrite?: TypeScriptConfigOverwrite;
  
  /**
   * Base directory for relative paths in TypeScript config
   * Defaults to webpack context directory
   */
  context?: string;
  
  /**
   * Enable TypeScript build mode (project references)
   * Uses TypeScript's build API for project references
   */
  build?: boolean;
  
  /**
   * Worker operating mode for different compilation scenarios
   */
  mode?: 'readonly' | 'write-tsbuildinfo' | 'write-dts' | 'write-references';
  
  /**
   * Diagnostic filtering and selection options
   */
  diagnosticOptions?: Partial<TypeScriptDiagnosticsOptions>;
  
  /**
   * Enable TypeScript performance profiling
   * Useful for debugging performance issues
   */
  profile?: boolean;
  
  /**
   * Path to custom TypeScript installation
   * Defaults to TypeScript resolved from node_modules
   */
  typescriptPath?: string;
}

/**
 * Memory limit for TypeScript worker process in MB
 * Recommended values:
 * - Small projects (< 100 files): 1024 MB
 * - Medium projects (100-1000 files): 2048 MB  
 * - Large projects (> 1000 files): 4096 MB or higher
 */
memoryLimit?: number;

// Conservative memory usage
new ForkTsCheckerWebpackPlugin({
  typescript: {
    memoryLimit: 1024 // 1GB
  }
})

// Large codebase configuration
new ForkTsCheckerWebpackPlugin({
  typescript: {
    memoryLimit: 8192 // 8GB for very large monorepos
  }
})

/**
 * Path to TypeScript configuration file
 * Can be absolute or relative to context directory
 */
configFile?: string;

/**
 * Configuration overrides to merge with tsconfig.json
 * Applied after loading base configuration
 */
configOverwrite?: TypeScriptConfigOverwrite;

/**
 * Base directory for resolving relative paths
 * Used as base for configFile and other relative paths
 */
context?: string;

// Different config files for different environments
new ForkTsCheckerWebpackPlugin({
  typescript: {
    configFile: process.env.NODE_ENV === 'production' 
      ? './tsconfig.prod.json' 
      : './tsconfig.dev.json'
  }
})

// Config overrides
new ForkTsCheckerWebpackPlugin({
  typescript: {
    configFile: './tsconfig.json',
    configOverwrite: {
      compilerOptions: {
        skipLibCheck: true,
        declaration: false
      }
    }
  }
})

// Custom context directory
new ForkTsCheckerWebpackPlugin({
  typescript: {
    context: path.resolve(__dirname, 'src'),
    configFile: '../tsconfig.json'
  }
})

/**
 * Enable TypeScript build mode for project references
 * Uses TypeScript's build API instead of regular compilation
 * Required for composite projects and project references
 */
build?: boolean;

// Project references setup
new ForkTsCheckerWebpackPlugin({
  typescript: {
    build: true,
    configFile: './tsconfig.json' // Should have "references" array
  }
})

/**
 * Worker operating mode for different compilation scenarios
 */
type WorkerMode = 
  | 'readonly'           // Read-only mode, no file writes
  | 'write-tsbuildinfo' // Write .tsbuildinfo for incremental compilation
  | 'write-dts'         // Write .d.ts declaration files
  | 'write-references'; // Write all output files including references

mode?: WorkerMode;

// Development - no file writes for speed
new ForkTsCheckerWebpackPlugin({
  typescript: {
    mode: 'readonly'
  }
})

// Production - generate all outputs
new ForkTsCheckerWebpackPlugin({
  typescript: {
    mode: 'write-references',
    build: true
  }
})

// Incremental builds - write tsbuildinfo only
new ForkTsCheckerWebpackPlugin({
  typescript: {
    mode: 'write-tsbuildinfo'
  }
})

/**
 * Diagnostic filtering and selection options
 * Provides fine-grained control over which TypeScript diagnostics to report
 */
diagnosticOptions?: Partial<TypeScriptDiagnosticsOptions>;

/**
 * Enable TypeScript performance profiling
 * Generates performance traces for debugging compilation speed
 */
profile?: boolean;

// Debug performance issues
new ForkTsCheckerWebpackPlugin({
  typescript: {
    profile: true,
    memoryLimit: 4096
  }
})

/**
 * Path to custom TypeScript installation
 * Useful for testing with different TypeScript versions
 */
typescriptPath?: string;

// Use beta TypeScript version
new ForkTsCheckerWebpackPlugin({
  typescript: {
    typescriptPath: require.resolve('typescript-beta')
  }
})

// Monorepo with shared TypeScript
new ForkTsCheckerWebpackPlugin({
  typescript: {
    typescriptPath: path.resolve(__dirname, '../../node_modules/typescript')
  }
})

/**
 * Configuration overrides to merge with tsconfig.json
 * Allows overriding any valid TypeScript configuration option
 */
interface TypeScriptConfigOverwrite {
  /** Extend from another configuration file */
  extends?: string;
  
  /** Compiler options to override or add */
  compilerOptions?: any;
  
  /** Files to include in compilation */
  include?: string[];
  
  /** Files to exclude from compilation */
  exclude?: string[];
  
  /** Specific files to compile */
  files?: string[];
  
  /** Project references for composite projects */
  references?: { path: string; prepend?: boolean }[];
}

/**
 * Options for controlling which TypeScript diagnostics to report
 */
interface TypeScriptDiagnosticsOptions {
  /** Enable syntactic diagnostics (syntax errors) */
  syntactic: boolean;
  
  /** Enable semantic diagnostics (type checking errors) */
  semantic: boolean;
  
  /** Enable declaration diagnostics (declaration file errors) */
  declaration: boolean;
  
  /** Enable global diagnostics (configuration errors) */
  global: boolean;
}