{"id":21296,"library":"esbuild-ts-paths","title":"esbuild-ts-paths","description":"A plugin for esbuild that resolves TypeScript path aliases defined in tsconfig.json to absolute paths during bundling. Current stable version is 1.1.3, released as needed. It wraps esbuild's build API and replaces path aliases (e.g., '@/*') with resolved absolute paths before esbuild processes the code. Key differentiator: it is a lightweight, zero-config plugin specifically designed for esbuild, unlike tsconfig-paths-webpack-plugin for Webpack or general-purpose alias resolvers. However, it is critical to note that this plugin performs a simple string replacement and may not handle all edge cases, such as path aliases in complex configurations or dynamic imports.","status":"active","version":"1.1.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/frankleng/esbuild-ts-paths","tags":["javascript"],"install":[{"cmd":"npm install esbuild-ts-paths","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-ts-paths","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-ts-paths","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; plugin interfaces with esbuild's build API.","package":"esbuild","optional":false},{"reason":"Optional; only needed if JSON schema validation of tsconfig is desired, but not enforced.","package":"typescript","optional":true}],"imports":[{"note":"Package is ESM-only; CommonJS require will fail.","wrong":"const esbuildTSPaths = require('esbuild-ts-paths')","symbol":"default","correct":"import esbuildTSPaths from 'esbuild-ts-paths'"},{"note":"Only default export exists; named import is incorrect.","wrong":"import { esbuildTSPaths } from 'esbuild-ts-paths'","symbol":"esbuildTSPaths","correct":"import esbuildTSPaths from 'esbuild-ts-paths'"},{"note":"TypeScript users should import the Plugin type from esbuild, not from this package.","wrong":null,"symbol":"Plugin type","correct":"import type { Plugin } from 'esbuild'"}],"quickstart":{"code":"import esbuild from 'esbuild';\nimport esbuildTSPaths from 'esbuild-ts-paths';\n\nawait esbuild.build({\n  entryPoints: ['src/index.ts'],\n  outfile: 'dist/bundle.js',\n  bundle: true,\n  plugins: [esbuildTSPPaths()],\n});","lang":"typescript","description":"Minimal setup showing how to use the plugin with esbuild to resolve TypeScript path aliases."},"warnings":[{"fix":"Manually resolve complex aliases or use an alternative resolver like tsx.","message":"The plugin performs simple string replacement and may not resolve aliases in all contexts (e.g., dynamic imports with expressions).","severity":"gotcha","affected_versions":"<=1.1.3"},{"fix":"Provide a custom tsconfig path via the plugin options: esbuildTSPPaths({ tsconfig: 'path/to/tsconfig.json' }).","message":"The plugin reads tsconfig.json automatically; if you have multiple tsconfig files, it may pick the wrong one.","severity":"gotcha","affected_versions":"<=1.1.3"},{"fix":"Use dynamic import or switch to ESM: import esbuildTSPaths from 'esbuild-ts-paths'.","message":"Version 1.0.0 changed from a CommonJS export to ESM-only. Requiring the package with require() will throw an error.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Remove the explicit tsconfig option if it points to the default tsconfig.json.","message":"The plugin's 'tsconfig' option was deprecated in v1.1.0 in favor of automatic detection; the option still works but may be removed in a future major version.","severity":"deprecated","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Change to dynamic import: const esbuildTSPaths = (await import('esbuild-ts-paths')).default; or use ESM.","cause":"Trying to require() an ESM-only package in a CommonJS context.","error":"Error: Must use import to load ES Module: /node_modules/esbuild-ts-paths/dist/index.js"},{"fix":"Import as default: import esbuildTSPaths from 'esbuild-ts-paths'.","cause":"Using named import { esbuildTSPaths } instead of default import.","error":"TypeError: esbuildTSPaths is not a function"},{"fix":"Check tsconfig.json for correct paths mapping and ensure plugin is attached to esbuild build.","cause":"The path alias '@utils/helper' is not defined in tsconfig paths, or the plugin is not applied correctly.","error":"Error: Could not resolve '@utils/helper'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}