esbuild-ts-paths

1.1.3 verified Mon Apr 27 auth: no javascript

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.

Common errors

error Error: Must use import to load ES Module: /node_modules/esbuild-ts-paths/dist/index.js ↓

cause Trying to require() an ESM-only package in a CommonJS context.

fix

Change to dynamic import: const esbuildTSPaths = (await import('esbuild-ts-paths')).default; or use ESM.

error TypeError: esbuildTSPaths is not a function ↓

cause Using named import { esbuildTSPaths } instead of default import.

fix

Import as default: import esbuildTSPaths from 'esbuild-ts-paths'.

error Error: Could not resolve '@utils/helper' ↓

cause The path alias '@utils/helper' is not defined in tsconfig paths, or the plugin is not applied correctly.

fix

Check tsconfig.json for correct paths mapping and ensure plugin is attached to esbuild build.

Warnings

gotcha The plugin performs simple string replacement and may not resolve aliases in all contexts (e.g., dynamic imports with expressions). ↓

fix Manually resolve complex aliases or use an alternative resolver like tsx.

gotcha The plugin reads tsconfig.json automatically; if you have multiple tsconfig files, it may pick the wrong one. ↓

fix Provide a custom tsconfig path via the plugin options: esbuildTSPPaths({ tsconfig: 'path/to/tsconfig.json' }).

breaking Version 1.0.0 changed from a CommonJS export to ESM-only. Requiring the package with require() will throw an error. ↓

fix Use dynamic import or switch to ESM: import esbuildTSPaths from 'esbuild-ts-paths'.

deprecated 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. ↓

fix Remove the explicit tsconfig option if it points to the default tsconfig.json.

Install

npm install esbuild-ts-paths

yarn add esbuild-ts-paths

pnpm add esbuild-ts-paths

Imports

default

wrong

const esbuildTSPaths = require('esbuild-ts-paths')

correct

import esbuildTSPaths from 'esbuild-ts-paths'

Package is ESM-only; CommonJS require will fail.

esbuildTSPaths

wrong

import { esbuildTSPaths } from 'esbuild-ts-paths'

correct

import esbuildTSPaths from 'esbuild-ts-paths'

Only default export exists; named import is incorrect.

Plugin type
```
import type { Plugin } from 'esbuild'
```
TypeScript users should import the Plugin type from esbuild, not from this package.

Quickstart

Minimal setup showing how to use the plugin with esbuild to resolve TypeScript path aliases.

import esbuild from 'esbuild';
import esbuildTSPaths from 'esbuild-ts-paths';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  outfile: 'dist/bundle.js',
  bundle: true,
  plugins: [esbuildTSPPaths()],
});