esbuild-dts-path-alias

4.2.1 verified Fri May 01 auth: no javascript

esbuild plugin for compiling TypeScript declaration files (.d.ts) with path alias transformation. Version 4.2.1 (latest) requires esbuild ^0.17.0, TypeScript >=5, and Node >=16.10.0. It resolves path aliases like '@utils/foo' into relative import paths in the output .d.ts files, solving a common pain point when using path aliases in TypeScript projects. It offers configurable tsconfig path, output directory, and debug logging. As a fork of esbuild-plugin-d-ts-alias, it maintains compatibility with recent esbuild and TypeScript versions. The plugin is ESM-only and ships TypeScript declarations.

Common errors

error require() of ES Module esbuild-plugin-d-ts-path-alias from node_modules not supported ↓

cause Using CommonJS require() to load an ESM-only package (v4+).

fix

Switch to ESM (set type: module in package.json or use .mjs extension) and use import syntax.

error Cannot find module 'esbuild-plugin-d-ts-path-alias' or its corresponding type declarations ↓

cause Missing installation or wrong import path when using TypeScript with strict moduleResolution.

fix

Install the package: npm install esbuild-plugin-d-ts-path-alias --save-dev. Ensure tsconfig.json has "moduleResolution": "node16" or "bundler".

error Error: tsconfig.json not found ↓

cause The plugin cannot locate tsconfig.json, or a custom tsconfigPath is incorrect.

fix

Provide explicit tsconfigPath option to dTSPathAliasPlugin({ tsconfigPath: './path/to/tsconfig.json' }) or ensure default tsconfig.json exists at project root.

Warnings

breaking Version 3.0.0 dropped support for TypeScript <5 and esbuild <0.17.0. ↓

fix Upgrade TypeScript to >=5 and esbuild to >=0.17.0, and Node to >=16.10.0.

breaking Version 4.0.0 changed to ESM-only package (type:module in package.json). ↓

fix Use dynamic import() or switch to ESM project configuration. For CommonJS require, pin to v3.x.

deprecated The original plugin was forked without indication of upstream changes. Check for newer versions. ↓

fix Monitor the GitHub repository for updates or consider forking as needed.

Install

npm install esbuild-dts-path-alias

yarn add esbuild-dts-path-alias

pnpm add esbuild-dts-path-alias

Imports

dTSPathAliasPlugin

wrong

const dTSPathAliasPlugin = require('esbuild-plugin-d-ts-path-alias')

correct

import { dTSPathAliasPlugin } from 'esbuild-plugin-d-ts-path-alias'

Package is ESM-only since v4.0.0. CommonJS require() will fail in Node ESM contexts.

dTSPathAliasPlugin (default export)
```
import dTSPathAliasPlugin from 'esbuild-plugin-d-ts-path-alias'
```
The plugin also supports default export for convenience, but named export is recommended for consistency.
PluginConfig (type)
```
import type { PluginConfig } from 'esbuild-plugin-d-ts-path-alias'
```
Type-only import for TypeScript users. PluginConfig includes tsconfigPath, outputPath, and debug options.

Quickstart

Demonstrates basic usage: include the plugin in esbuild build config to transform path aliases in .d.ts files.

import { build } from 'esbuild';
import { dTSPathAliasPlugin } from 'esbuild-plugin-d-ts-path-alias';

build({
  entryPoints: ['./src/index.ts'],
  outfile: './dist/index.js',
  bundle: true,
  format: 'esm',
  target: 'es2020',
  plugins: [dTSPathAliasPlugin()],
}).catch(() => process.exit(1));