ts-loader: TypeScript loader for webpack

Common errors

• Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders

  cause Webpack encountered a TypeScript file (e.g., `.ts`, `.tsx`) but `ts-loader` was not configured or applied to handle it in `webpack.config.js`.
  fix Add a rule to `module.rules` in your `webpack.config.js` to process TypeScript files with `ts-loader`: `{ test: /\.tsx?$/, use: 'ts-loader', exclude: /node_modules/ }`. Also ensure `.ts` and `.tsx` are included in `resolve.extensions`.

• Error: Cannot find module 'typescript' from '...' (ts-loader)

  cause The `typescript` package, a required peer dependency for `ts-loader`, is not installed in the project.
  fix Install TypeScript as a development dependency: `npm install typescript --save-dev` or `yarn add typescript --dev`.

• ERROR in ts-loader\index.js!./src/index.ts
  TS2307: Cannot find module '...' or its corresponding type declarations.

  cause TypeScript's module resolution failed, often due to an incorrect `tsconfig.json` configuration (e.g., `baseUrl`, `paths`), missing type declarations, or an incorrectly specified `configFile` option in `ts-loader`.
  fix Verify your `tsconfig.json` is correctly configured for module resolution, including `baseUrl` and `paths` if needed. Ensure all necessary `@types/*` packages are installed. If using a custom `tsconfig.json` path, check the `options.configFile` in `webpack.config.js`.

• ERROR in ts-loader\index.js!./src/app.ts
  (5,3): error TS1005: ',' expected.

  cause A general TypeScript compilation error within `ts-loader`, indicating an issue with the TypeScript code itself or a compatibility problem between the installed TypeScript version and the code/types being processed.
  fix Review the indicated TypeScript file and line number for syntax errors. Ensure your TypeScript version is compatible with your project's code and installed `@types` packages, upgrading TypeScript if necessary.

Warnings

• breaking ts-loader v9.0.0 introduced breaking changes, requiring webpack 5+ and Node.js 12+. Projects using older webpack or Node.js versions must use ts-loader v8.x or migrate their environment.
  Fix: Upgrade webpack to v5+ and Node.js to v12+ if upgrading to ts-loader v9+. Otherwise, stick to ts-loader v8.x for webpack 4 compatibility.
• gotcha `ts-loader` is a webpack loader and requires `typescript` as a peer dependency. Failing to install `typescript` separately will result in build errors indicating that the TypeScript compiler cannot be found or initialized.
  Fix: Ensure `typescript` is installed in your project's dev dependencies: `npm install typescript --save-dev` or `yarn add typescript --dev`.
• gotcha For larger projects, `ts-loader` can cause slow build times due to performing type checking synchronously. It's highly recommended to use the `transpileOnly: true` option in conjunction with `fork-ts-checker-webpack-plugin` to run type checking in a separate process.
  Fix: Set `transpileOnly: true` in your `ts-loader` options and add `new ForkTsCheckerWebpackPlugin()` to your webpack `plugins` array.
• breaking ts-loader versions prior to 9.5.7 experienced `TS5011` errors with TypeScript 6.0 due to `transpileModule` being called with `rootDir: undefined`. This can lead to compilation failures when using newer TypeScript versions.
  Fix: Upgrade `ts-loader` to version `9.5.7` or newer when using TypeScript 6.0+. Ensure `rootDir` is explicitly defined in your `tsconfig.json` for robustness.
• gotcha Versions 9.5.5 and 9.5.6 of `ts-loader` were skipped due to publishing issues. Users should ensure they are on `9.5.7` or a newer version to receive all latest fixes and features.
  Fix: Upgrade to `ts-loader@9.5.7` or the latest stable version.

Install

• npm install ts-loader npm
• yarn add ts-loader yarn
• pnpm add ts-loader pnpm

Imports

• 'ts-loader'
  wrong:

  import tsLoader from 'ts-loader'; // ts-loader is a webpack loader, not a direct JS module export for runtime use.

  correct:

  module.exports = {
    // ...
    module: {
      rules: [
        {
          test: /\.tsx?$/,
          loader: 'ts-loader',
          options: {
            // loader options
          }
        }
      ]
    }
  };

  ts-loader is configured within your webpack.config.js as a rule, identified by its string name. It is not imported directly into application code.
• transpileOnly

  {
    loader: 'ts-loader',
    options: {
      transpileOnly: true,
    }
  }

  Setting `transpileOnly: true` disables type checking during compilation, significantly speeding up build times. Type checking can then be offloaded to `fork-ts-checker-webpack-plugin` for parallel execution.
• configFile

  {
    loader: 'ts-loader',
    options: {
      configFile: 'path/to/your/tsconfig.build.json',
    }
  }

  Allows specifying a custom path to a `tsconfig.json` file, overriding the default behavior of searching in the project root or entry point's directory.

Quickstart

This quickstart configures webpack to use `ts-loader` for transpiling TypeScript files, including source map generation and integrating `fork-ts-checker-webpack-plugin` for optimized type checking during development.

const path = require('path');
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

module.exports = {
  mode: 'development',
  entry: './src/index.ts',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  resolve: {
    extensions: ['.ts', '.tsx', '.js'],
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: {
          loader: 'ts-loader',
          options: {
            // Enable faster transpilation by skipping type checking, often paired with ForkTsCheckerWebpackPlugin
            transpileOnly: true,
          },
        },
        exclude: /node_modules/,
      },
    ],
  },
  plugins: [
    // Run type checking in a separate process for performance
    new ForkTsCheckerWebpackPlugin(),
  ],
  devtool: 'inline-source-map',
  // Example tsconfig.json (tsconfig.json in project root):
  // {
  //   "compilerOptions": {
  //     "outDir": "./dist/",
  //     "sourceMap": true,
  //     "noImplicitAny": true,
  //     "module": "esnext",
  //     "target": "es2017",
  //     "jsx": "react",
  //     "lib": ["dom", "esnext"]
  //   },
  //   "include": ["src"]
  // }
};