awesome-typescript-loader

awesome-typescript-loader is a high-performance TypeScript webpack loader that enables compilation of TypeScript files in webpack-based projects. It offers advanced features including first-class Babel integration with caching capabilities, forked type-checking and compilation for faster development cycles, and support for complex TypeScript configurations including path mapping and custom transformers.

Package Information

• Package Name: awesome-typescript-loader
• Package Type: npm
• Language: TypeScript
• Version: 5.2.1
• Installation: npm install awesome-typescript-loader --save-dev

Package Metadata

• Main Entry: dist/entry.js
• TypeScript Definitions: ./dist/index.d.ts
• Peer Dependencies: TypeScript ^2.7 || ^3
• Supported Node.js: 4 and newer

Core Imports

// Main loader - used in webpack configuration
const loader = require('awesome-typescript-loader');

For additional plugins:

const { CheckerPlugin, TsConfigPathsPlugin } = require('awesome-typescript-loader');

Basic Usage

Basic webpack configuration:

const { CheckerPlugin } = require('awesome-typescript-loader');

module.exports = {
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx']
  },
  module: {
    rules: [{
      test: /\.tsx?$/,
      loader: 'awesome-typescript-loader'
    }]
  },
  plugins: [
    new CheckerPlugin()
  ]
};

With configuration options:

module.exports = {
  module: {
    rules: [{
      test: /\.tsx?$/,
      loader: 'awesome-typescript-loader',
      options: {
        useCache: true,
        useBabel: true,
        transpileOnly: false,
        configFileName: 'tsconfig.json'
      }
    }]
  }
};

Architecture

awesome-typescript-loader is built around several key components:

• Main Loader: Core webpack loader function that handles TypeScript compilation with async callback system
• Instance Management: Support for multiple TypeScript compiler instances with different settings, each maintaining its own configuration, checker, and compilation state
• Checker System: Asynchronous type checking that can fork to separate processes for faster development cycles, enabled via CheckerPlugin
• Caching Layer: File-level caching with SHA-512 checksum-based invalidation for improved performance, supporting both TypeScript and Babel transformation caching
• Babel Integration: Optional Babel transpilation after TypeScript compilation with configurable presets and options
• Plugin System: Webpack plugins for enhanced functionality:
  • CheckerPlugin: Enables async error reporting and watch mode detection
  • TsConfigPathsPlugin: TypeScript path mapping support based on tsconfig.json paths configuration
• Watch Mode Detection: Symbol-based system to track webpack watch vs production builds
• Path Resolution: Full TypeScript 2.0+ path mapping support integrated with webpack's enhanced-resolve system

Capabilities

TypeScript Loader

Core webpack loader functionality for compiling TypeScript files to JavaScript with full webpack integration.

/**
 * Main TypeScript loader function for webpack
 * Handles compilation of .ts/.tsx files to JavaScript
 */
function loader(text: string): void;

namespace loader {
  export const TsConfigPathsPlugin: typeof PathPlugin;
  export const CheckerPlugin: typeof CheckerPluginClass;
}

Core Loader

Configuration Options

Comprehensive configuration system for customizing TypeScript compilation, Babel integration, caching, and performance optimization.

interface LoaderConfig {
  instance?: string;
  compiler?: string;
  configFileName?: string;
  configFileContent?: string;
  transpileOnly?: boolean;
  useCache?: boolean;
  useBabel?: boolean;
  forceIsolatedModules?: boolean;
  errorsAsWarnings?: boolean;
  silent?: boolean;
  // ... additional options
}

Configuration

Webpack Plugins

Essential webpack plugins for enhanced functionality including async error reporting and TypeScript path mapping support.

class CheckerPlugin {
  apply(compiler: any): void;
}

class TsConfigPathsPlugin {
  constructor(config?: LoaderConfig & ts.CompilerOptions & PathPluginOptions);
  apply(resolver: Resolver): void;
}

Plugins

Types

interface LoaderConfig {
  instance?: string;
  compiler?: string;
  configFileName?: string;
  configFileContent?: string;
  forceIsolatedModules?: boolean;
  errorsAsWarnings?: boolean;
  transpileOnly?: boolean;
  ignoreDiagnostics?: number[];
  compilerOptions?: ts.CompilerOptions;
  useTranspileModule?: boolean;
  useBabel?: boolean;
  babelCore?: string;
  babelOptions?: any;
  usePrecompiledFiles?: boolean;
  silent?: boolean;
  useCache?: boolean;
  cacheDirectory?: string;
  entryFileIsJs?: boolean;
  debug?: boolean;
  reportFiles?: string[];
  context?: string;
  getCustomTransformers?: string | ((program: ts.Program) => ts.CustomTransformers | undefined);
}

interface PathPluginOptions {
  context?: string;
}