Registry / devops / esbuild-ts-paths

esbuild-ts-paths

library1.1.3jsnpmunverified

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.

devops serialization

npm install esbuild-ts-paths

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-TS-PATHS

esbuild-ts-paths

devopsjavascriptv1.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import esbuildTSPaths from 'esbuild-ts-paths'

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

Package is ESM-only; CommonJS require will fail.

esbuildTSPaths

✓ import esbuildTSPaths from 'esbuild-ts-paths'

✗ 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.

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()], });

Debug

Known issues

gotchaThe 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.

affects: <=1.1.3

gotchaThe 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' }).

affects: <=1.1.3

breakingVersion 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'.

affects: >=1.0.0

deprecatedThe 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.

affects: >=1.1.0

Errors

Common errors & fixes

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

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.

TypeError: esbuildTSPaths is not a function

Using named import { esbuildTSPaths } instead of default import.

fix

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

Error: Could not resolve '@utils/helper'

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.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency; plugin interfaces with esbuild's build API.

typescriptoptionalOptional; only needed if JSON schema validation of tsconfig is desired, but not enforced.

Agent activity

8 hits · last 30 days

node

Amazon

Bingbot

Resources

githubhttps://github.com/frankleng/esbuild-ts-paths ↗

packagehttps://www.npmjs.com/package/esbuild-ts-paths ↗