{"id":25329,"library":"esbuild-plugin-d-ts-path-alias","title":"esbuild-plugin-d-ts-path-alias","description":"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.","status":"active","version":"4.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/ArtemKlyuev/esbuild-plugin-d-ts-path-alias","tags":["javascript","typescript","compiler","esbuild","plugin","declaration","dts"],"install":[{"cmd":"npm install esbuild-plugin-d-ts-path-alias","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-d-ts-path-alias","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-d-ts-path-alias","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency for the build pipeline","package":"esbuild","optional":false},{"reason":"peer dependency to compile declarations","package":"typescript","optional":false}],"imports":[{"note":"Package is ESM-only since v4.0.0. CommonJS require() will fail.","wrong":"const dTSPathAliasPlugin = require('esbuild-plugin-d-ts-path-alias')","symbol":"dTSPathAliasPlugin","correct":"import { dTSPathAliasPlugin } from 'esbuild-plugin-d-ts-path-alias'"},{"note":"Named export dTSPathAliasPlugin is preferred; default export also available.","wrong":"import { default as dTSPathAliasPlugin } from 'esbuild-plugin-d-ts-path-alias'","symbol":"default","correct":"import dTSPathAliasPlugin from 'esbuild-plugin-d-ts-path-alias'"},{"note":"TypeScript users can import the config interface for type safety.","symbol":"DtsPluginConfig","correct":"import type { DtsPluginConfig } from 'esbuild-plugin-d-ts-path-alias'"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport { dTSPathAliasPlugin } from 'esbuild-plugin-d-ts-path-alias';\n\nawait build({\n  bundle: true,\n  target: 'es2019',\n  format: 'esm',\n  entryPoints: ['./src/index.ts'],\n  outfile: './build/out.js',\n  plugins: [dTSPathAliasPlugin()],\n});","lang":"typescript","description":"Demonstrates minimal usage: import plugin, pass to esbuild build call with entry point and output file."},"warnings":[{"fix":"Use import statement or dynamic import(). If you need CommonJS, stay on v3.x.","message":"v4.0.0 upgraded to ESM-only package. require() will throw ERR_REQUIRE_ESM.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update TypeScript to >=5.0 and esbuild to ^0.17.0 or higher.","message":"v3.0.0 requires TypeScript >=5.0 and esbuild ^0.17.0. Older versions incompatible.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Explicitly set outputPath in plugin config to avoid ambiguity.","message":"If esbuild config has both outdir and outfile, the plugin may default to esbuild's outdir for declaration output if no outputPath specified.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to v3.x or later to support TypeScript >=5.0.","message":"v2.0.0 restricted TypeScript version to <4.8, which is outdated.","severity":"deprecated","affected_versions":"2.0.0"},{"fix":"Ensure tsconfig.json includes paths mapping, e.g., \"@utils/*\": [\"./src/utils/*\"].","message":"Plugin expects tsconfig.json to have compilerOptions.paths defined; otherwise no alias resolution occurs.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Change to import { dTSPathAliasPlugin } from 'esbuild-plugin-d-ts-path-alias' or use dynamic import.","cause":"Using CommonJS require() with package that is ESM-only since v4.0.0.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /node_modules/esbuild-plugin-d-ts-path-alias/... from not supported."},{"fix":"Ensure package is installed and import statement uses named export: import { dTSPathAliasPlugin } from 'esbuild-plugin-d-ts-path-alias'.","cause":"TypeScript not recognizing the export due to missing type declaration or incorrect import.","error":"Cannot find name 'dTSPathAliasPlugin'. Did you mean 'dTSPathAliasPlugin'?"},{"fix":"Create a tsconfig.json or pass a custom path: dTSPathAliasPlugin({ tsconfigPath: './config/tsconfig.json' }).","cause":"Missing or inaccessible tsconfig.json in the project root.","error":"Error: No tsconfig.json found. If you are using a custom path, provide it via tsconfigPath option."},{"fix":"Set outdir or outfile in esbuild build options, or provide outputPath in plugin config.","cause":"Plugin cannot determine where to output .d.ts files because esbuild's outdir/outfile is missing.","error":"(plugin d-ts-path-alias) Error: esbuild outdir/outfile not set. Declaration output destination unknown."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}