tsconfig-paths-webpack-plugin

4.2.0 verified Sat Apr 25 auth: no javascript

A webpack resolve plugin that automatically creates alias entries based on the `paths` and `baseUrl` in your `tsconfig.json`, eliminating the need to manually duplicate those mappings in your webpack config. Version 4.2.0 supports webpack 5+ and ships TypeScript types. Stable, widely used in TypeScript monorepos and migration scenarios. Distinct from manual alias configuration or alternative tools like `tsconfig-paths` as it integrates directly into webpack's resolution pipeline.

Common errors

error Module not found: Error: Can't resolve '@alias/some-module' ↓

cause Plugin not configured or paths not aligned with tsconfig.json.

fix

Ensure tsconfig-paths-webpack-plugin is added to resolve.plugins and tsconfig.json has correct paths.

error Cannot read property 'apply' of undefined ↓

cause Misplaced plugin in root 'plugins' instead of 'resolve.plugins'.

fix

Move plugin to resolve: { plugins: [...] } in webpack config.

error TypeError: Cannot destructure property 'getPlugin' of '...' as it is undefined. ↓

cause Using webpack 4 with version 4 of the plugin.

fix

Downgrade plugin to v3 (npm install tsconfig-paths-webpack-plugin@3) or upgrade webpack to 5.

error Error: The 'compilation' argument must be an instance of Compilation ↓

cause Plugin instantiated incorrectly or multiple resolver plugins conflict.

fix

Ensure only one instance of TsconfigPathsPlugin is added and it's a valid resolver plugin.

error Warning: No configuration file (tsconfig.json) found. ↓

cause Missing tsconfig.json or incorrect configFile path.

fix

Create tsconfig.json or set absolute path for configFile option.

Warnings

breaking Version 4 changed the plugin from a named export to a default export. ↓

fix Replace `import { TsconfigPathsPlugin } from 'tsconfig-paths-webpack-plugin'` with `import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin'`.

breaking Version 4 requires webpack 5+; webpack 4 support dropped. ↓

fix Upgrade to webpack 5 or use tsconfig-paths-webpack-plugin@3 for webpack 4.

deprecated The `logLevel` option may be removed in future; prefer `silent: true` to suppress logs. ↓

fix Use `silent: true` instead of `logLevel: 'warn'`.

breaking Node.js >=10.13.0 required; older versions not supported. ↓

fix Update Node.js to >=10.13.0 or use tsconfig-paths-webpack-plugin@3.

gotcha The plugin must be placed in `resolve.plugins`, not in the root `plugins` array. ↓

fix Move the plugin instance to the `resolve.plugins` array in your webpack config.

gotcha If using `allowJs` in tsconfig.json, ensure `extensions` option includes `.js` and `.jsx`, otherwise resolution may fail. ↓

fix Set `extensions: ['.ts', '.tsx', '.js', '.jsx']` (or match your webpack resolve.extensions).

gotcha The plugin does not respect webpack's `resolve.extensions` automatically; you must set `extensions` option explicitly. ↓

fix Manually pass the same extensions as in your webpack `resolve.extensions` to the plugin.

Install

npm install tsconfig-paths-webpack-plugin

yarn add tsconfig-paths-webpack-plugin

pnpm add tsconfig-paths-webpack-plugin

Imports

TsconfigPathsPlugin
wrong
```
const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin').default
```
correct
```
import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin'
```
Default export; CommonJS require works directly without .default in v4, but using import is preferred for TypeScript.
TsconfigPathsPlugin
wrong
```
import { TsconfigPathsPlugin } from 'tsconfig-paths-webpack-plugin'
```
correct
```
const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin')
```
Versions <4 required named import via 'import { TsconfigPathsPlugin }' but v4 changed to default export. Named import will fail.

type TsconfigPathsPluginOptions

wrong

import { TsconfigPathsPluginOptions } from 'tsconfig-paths-webpack-plugin'

correct

import type { TsconfigPathsPluginOptions } from 'tsconfig-paths-webpack-plugin'

Options type is exported as a named type; use 'import type' for TypeScript to avoid runtime issues.

Quickstart

Basic webpack configuration adding the plugin to resolve.plugins with common options.

// webpack.config.cjs
const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

module.exports = {
  resolve: {
    plugins: [
      new TsconfigPathsPlugin({
        configFile: './tsconfig.json',
        extensions: ['.ts', '.tsx', '.js', '.jsx'],
        silent: true
      })
    ]
  }
};