or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-tsconfig-paths-webpack-plugin

Load modules according to tsconfig paths in webpack.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/tsconfig-paths-webpack-plugin@4.2.x

To install, run

npx @tessl/cli install tessl/npm-tsconfig-paths-webpack-plugin@4.2.0

index.mddocs/

TsconfigPathsPlugin

TsconfigPathsPlugin is a webpack resolver plugin that enables automatic module resolution based on TypeScript path mapping configuration from tsconfig.json. It eliminates the need for manual webpack alias configuration by reading the paths section from tsconfig.json and creating corresponding aliases automatically.

Package Information

  • Package Name: tsconfig-paths-webpack-plugin
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev tsconfig-paths-webpack-plugin

Core Imports

import TsconfigPathsPlugin from "tsconfig-paths-webpack-plugin";

Named import:

import { TsconfigPathsPlugin } from "tsconfig-paths-webpack-plugin";

For CommonJS:

const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

Basic Usage

const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

module.exports = {
  resolve: {
    plugins: [new TsconfigPathsPlugin()]
  }
};

With configuration options:

const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

module.exports = {
  resolve: {
    plugins: [
      new TsconfigPathsPlugin({
        configFile: "./tsconfig.json",
        extensions: [".ts", ".tsx", ".js"],
        mainFields: ["browser", "main"],
        logLevel: "warn"
      })
    ]
  }
};

Architecture

TsconfigPathsPlugin integrates with webpack's resolve system through the ResolvePluginInstance interface. It:

  • Parses tsconfig.json: Reads TypeScript configuration files to extract path mappings
  • Creates Path Matchers: Uses the tsconfig-paths library to create async path matching functions
  • Hooks into Webpack Resolver: Implements webpack's resolver plugin interface to intercept module resolution
  • Supports References: Handles TypeScript project references for monorepo scenarios
  • Legacy Compatibility: Supports both modern webpack (4+) and legacy webpack (<4) plugin systems

Capabilities

TsconfigPathsPlugin Class

Main webpack resolver plugin that resolves modules using tsconfig.json paths configuration.

/**
 * Webpack resolver plugin for TypeScript path mapping
 */
class TsconfigPathsPlugin implements ResolvePluginInstance {
  /**
   * Creates a new TsconfigPathsPlugin instance
   * @param rawOptions - Configuration options (defaults to empty object)
   */
  constructor(rawOptions: Partial<Options> = {});
  
  /**
   * Webpack plugin interface method - called by webpack resolver
   * @param resolver - The webpack resolver instance
   */
  apply(resolver: Resolver): void;
}

Usage Examples:

// Basic usage with defaults
const plugin = new TsconfigPathsPlugin();

// With TypeScript import
import TsconfigPathsPlugin from "tsconfig-paths-webpack-plugin";
const plugin = new TsconfigPathsPlugin({
  configFile: "./src/tsconfig.json",
  extensions: [".ts", ".tsx", ".js", ".jsx"]
});

// For monorepos with project references
const plugin = new TsconfigPathsPlugin({
  references: ["./packages/core/tsconfig.json", "./packages/utils/tsconfig.json"]
});

Configuration Options

All configuration options for customizing plugin behavior.

interface Options {
  /** Path to tsconfig.json file - can be filename, relative path, or absolute path */
  readonly configFile: string;
  /** File extensions to try during module resolution */
  readonly extensions: ReadonlyArray<string>;
  /** Override baseUrl from tsconfig.json */
  readonly baseUrl: string | undefined;
  /** Suppress console log messages */
  readonly silent: boolean;
  /** Logging level for plugin messages */
  readonly logLevel: LogLevel;
  /** Output info logs to stdout instead of stderr */
  readonly logInfoToStdOut: boolean;
  /** Context directory for resolving relative paths */
  readonly context: string | undefined;
  /** Enable colored terminal output */
  readonly colors: boolean;
  /** Package.json fields to consider when resolving packages */
  readonly mainFields: (string | string[])[];
  /** TypeScript project references for monorepo support */
  readonly references: string[] | undefined;
}

type LogLevel = "INFO" | "WARN" | "ERROR";

Default Values:

  • configFile: "tsconfig.json"
  • extensions: [".ts", ".tsx"]
  • baseUrl: undefined (uses tsconfig.json value)
  • silent: false
  • logLevel: "WARN"
  • logInfoToStdOut: false
  • context: undefined (uses current working directory)
  • colors: true
  • mainFields: ["main"]
  • references: undefined

Usage Examples:

// Custom tsconfig location
new TsconfigPathsPlugin({
  configFile: "./src/tsconfig.build.json"
});

// Support additional file extensions
new TsconfigPathsPlugin({
  extensions: [".ts", ".tsx", ".js", ".jsx", ".vue"]
});

// Override baseUrl for build scenarios
new TsconfigPathsPlugin({
  baseUrl: "./dist"
});

// Silent mode for production builds
new TsconfigPathsPlugin({
  silent: true
});

// Debug mode with detailed logging
new TsconfigPathsPlugin({
  logLevel: "INFO",
  logInfoToStdOut: true
});

// Browser-compatible package resolution
new TsconfigPathsPlugin({
  mainFields: ["browser", "module", "main"]
});

// Monorepo with project references
new TsconfigPathsPlugin({
  references: [
    "./packages/core/tsconfig.json",
    "./packages/shared/tsconfig.json"
  ]
});

Logger Interface

Internal logging system used by the plugin.

interface Logger {
  /** General logging output */
  log: LoggerFunc;
  /** Info level messages */
  logInfo: LoggerFunc;
  /** Warning level messages */
  logWarning: LoggerFunc;
  /** Error level messages */
  logError: LoggerFunc;
}

type LoggerFunc = (message: string) => void;

Types

/**
 * Webpack resolver instance interface (from webpack)
 */
interface Resolver {
  readonly fileSystem: FileSystem;
  getHook?(hook: string): AsyncSeriesBailHook<[ResolveRequest, ResolveContext], null | ResolveRequest>;
  doResolve: Function;
}

/**
 * Webpack resolve plugin interface
 */
interface ResolvePluginInstance {
  apply(resolver: Resolver): void;
}

/**
 * File system interface used by webpack resolver
 */
interface FileSystem {
  readFile: Function;
  stat: Function;
}

Error Handling

The plugin handles several error conditions:

  • Missing tsconfig.json: Logs error and disables path resolution
  • Invalid tsconfig.json: Logs parsing errors with file location
  • Resolver placement errors: Warns if plugin is not in resolve.plugins array
  • File system errors: Gracefully handles missing files during resolution
  • Path resolution failures: Falls back to webpack's default resolution

Common error messages:

"Failed to load tsconfig.json: [error details]"
"No file system found on resolver. Please make sure you've placed the plugin in the correct part of the configuration."
"Found no resolver, not applying tsconfig-paths-webpack-plugin"