esbuild-plugin-d-ts-path-alias

4.2.0 verified Fri May 01 auth: no javascript

esbuild plugin for compiling TypeScript declaration files (.d.ts) with automatic path alias resolution. Current stable version: 4.2.0 (June 2023). Release cadence: irregular, with major version bumps for esbuild and TypeScript peer dependency updates. Key differentiators: integrates directly into esbuild build pipeline, transforms path aliases like @utils/foo to relative imports in emitted .d.ts files, supports custom tsconfig and output paths. Requires esbuild ^0.17.0 || ^0.18.0 and TypeScript >=5.0, Node >=16.10.0. The plugin resolves tsconfig paths, runs TypeScript compiler for declaration emit, then rewrites alias imports to relative paths. Ships TypeScript types and is ESM-only.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /node_modules/esbuild-plugin-d-ts-path-alias/... from not supported. ↓

cause Using CommonJS require() with package that is ESM-only since v4.0.0.

fix

Change to import { dTSPathAliasPlugin } from 'esbuild-plugin-d-ts-path-alias' or use dynamic import.

error Cannot find name 'dTSPathAliasPlugin'. Did you mean 'dTSPathAliasPlugin'? ↓

cause TypeScript not recognizing the export due to missing type declaration or incorrect import.

fix

Ensure package is installed and import statement uses named export: import { dTSPathAliasPlugin } from 'esbuild-plugin-d-ts-path-alias'.

error Error: No tsconfig.json found. If you are using a custom path, provide it via tsconfigPath option. ↓

cause Missing or inaccessible tsconfig.json in the project root.

fix

Create a tsconfig.json or pass a custom path: dTSPathAliasPlugin({ tsconfigPath: './config/tsconfig.json' }).

error (plugin d-ts-path-alias) Error: esbuild outdir/outfile not set. Declaration output destination unknown. ↓

cause Plugin cannot determine where to output .d.ts files because esbuild's outdir/outfile is missing.

fix

Set outdir or outfile in esbuild build options, or provide outputPath in plugin config.

Warnings

breaking v4.0.0 upgraded to ESM-only package. require() will throw ERR_REQUIRE_ESM. ↓

fix Use import statement or dynamic import(). If you need CommonJS, stay on v3.x.

breaking v3.0.0 requires TypeScript >=5.0 and esbuild ^0.17.0. Older versions incompatible. ↓

fix Update TypeScript to >=5.0 and esbuild to ^0.17.0 or higher.

gotcha If esbuild config has both outdir and outfile, the plugin may default to esbuild's outdir for declaration output if no outputPath specified. ↓

fix Explicitly set outputPath in plugin config to avoid ambiguity.

deprecated v2.0.0 restricted TypeScript version to <4.8, which is outdated. ↓

fix Upgrade to v3.x or later to support TypeScript >=5.0.

gotcha Plugin expects tsconfig.json to have compilerOptions.paths defined; otherwise no alias resolution occurs. ↓

fix Ensure tsconfig.json includes paths mapping, e.g., "@utils/*": ["./src/utils/*"].

Install

npm install esbuild-plugin-d-ts-path-alias

yarn add esbuild-plugin-d-ts-path-alias

pnpm add esbuild-plugin-d-ts-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.

default

wrong

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

correct

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

Named export dTSPathAliasPlugin is preferred; default export also available.

DtsPluginConfig
```
import type { DtsPluginConfig } from 'esbuild-plugin-d-ts-path-alias'
```
TypeScript users can import the config interface for type safety.

Quickstart

Demonstrates minimal usage: import plugin, pass to esbuild build call with entry point and output file.

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

await build({
  bundle: true,
  target: 'es2019',
  format: 'esm',
  entryPoints: ['./src/index.ts'],
  outfile: './build/out.js',
  plugins: [dTSPathAliasPlugin()],
});