awesome-typescript-loader

5.2.1 verified Sat Apr 25 auth: no javascript maintenance

A TypeScript loader for Webpack 4.x that integrates with Babel and supports caching and forked type-checking. v5.2.1 is the latest stable release, targeting TypeScript 2.7+ and Webpack 4. Notably, the loader can fork the type-checker to a separate process for faster development builds. Offers first-class Babel integration with caching, significantly reducing rebuild times when combined. However, for Windows users, paths may need correction. The loader is considered a mature alternative to ts-loader but slower for some workloads; consider ts-loader with HappyPack or thread-loader for those cases. See GitHub for full README.

Common errors

error Loader did not return a buffer or string ↓

cause File path mismatches on case-insensitive file systems due to incorrect path casing in tsconfig.

fix

Ensure all paths in tsconfig.json use consistent casing and forward slashes.

error TypeError: Cannot read property 'version' of undefined ↓

cause Missing or incompatible peer dependency 'typescript' not installed or wrong version.

fix

Install TypeScript: npm install typescript --save-dev. Ensure version matches peer requirement (^2.7 || ^3).

error Error: The 'CheckerPlugin' is only allowed when using watch mode or when using webpack-dev-server. ↓

cause CheckerPlugin requires watch mode; it cannot be used in production builds without WatchIgnorePlugin.

fix

Remove CheckerPlugin for production builds or add WatchIgnorePlugin to ignore node_modules. Alternatively, use 'forceIsolatedModules' to skip type checking in production.

Warnings

gotcha On case-insensitive file systems (Windows/macOS), file path mismatches can cause 'Loader did not return a buffer of string' errors. Use Unix-style paths in tsconfig include/exclude. ↓

fix Use forward slashes in paths (e.g., './src/**/*.ts' instead of '.\src\**\*.ts').

deprecated Use of minimatch for file filtering in tsconfig was replaced by micromatch in v3.2.0. ↓

fix Upgrade to v3.2.0 or later; micromatch is more performant.

gotcha The loader does not support HappyPack or thread-loader directly; for parallel builds, consider ts-loader with those plugins. ATL works better with hard-source-webpack-plugin for caching. ↓

fix Use hard-source-webpack-plugin for build caching; do not combine with thread-loader.

breaking Version 5.0.0 dropped support for TypeScript < 2.7 and Webpack < 4. ↓

fix Ensure you have TypeScript ^2.7 or ^3 and webpack 4.x.

deprecated The 'silent' option may not silence all output; CheckerPlugin is needed for proper error reporting in watch mode. ↓

fix Use CheckerPlugin and optionally set 'errorsAsWarnings' to true.

Install

npm install awesome-typescript-loader

yarn add awesome-typescript-loader

pnpm add awesome-typescript-loader

Imports

awesome-typescript-loader
wrong
```
const atl = require('awesome-typescript-loader')
```
correct
```
module.exports = { module: { rules: [ { test: /\.tsx?$/, loader: 'awesome-typescript-loader' } ] } }
```
Use as a webpack loader rule, not as a direct import. The loader is configured via webpack config, not imported in source code.
CheckerPlugin
wrong
```
import { CheckerPlugin } from 'awesome-typescript-loader'
```
correct
```
const { CheckerPlugin } = require('awesome-typescript-loader')
```
CheckerPlugin is a named export that is CommonJS exported. Use require for webpack config files (CJS). ESM import also works in webpack config, but require is common.

LoaderOptions

wrong

const LoaderOptions = require('awesome-typescript-loader').LoaderOptions

correct

import { LoaderOptions } from 'awesome-typescript-loader'

TypeScript type import for loader options. Use import type for type-only imports if desired.

Quickstart

Minimal webpack configuration using awesome-typescript-loader with CheckerPlugin for async error reporting.

// webpack.config.js
const path = require('path');
const { CheckerPlugin } = require('awesome-typescript-loader');

module.exports = {
  entry: './src/index.ts',
  output: { path: path.resolve(__dirname, 'dist'), filename: 'bundle.js' },
  resolve: { extensions: ['.ts', '.tsx', '.js', '.jsx'] },
  devtool: 'source-map',
  module: { rules: [ { test: /\.tsx?$/, loader: 'awesome-typescript-loader' } ] },
  plugins: [ new CheckerPlugin() ]
};