Registry / devops / esbuild-plugin-tsconfig-paths

esbuild-plugin-tsconfig-paths

library1.0.2jsnpmunverified

An esbuild plugin that converts TypeScript path aliases defined in tsconfig.json's compilerOptions.paths to relative import paths during build. This avoids the need for runtime alias resolution, making output bundles self-contained and easier to distribute. Version 1.0.2 is the latest stable release with TypeScript type declarations and compatibility fixes. It works by hooking into esbuild's onLoad phase, rewriting static import statements that match the configured paths. Key differentiators: lightweight, zero runtime dependencies, focused solely on path transformation without affecting other esbuild behavior. Compared to alternatives like tsconfig-paths-webpack-plugin or vite-tsconfig-paths, this plugin is designed specifically for esbuild's streaming, fast build pipeline.

devops

npm install esbuild-plugin-tsconfig-paths

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-TSC

esbuild-plugin-tsconfig-paths

devopsjavascriptv1.0.2

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.

tsconfigPathsPlugin

✓ import { tsconfigPathsPlugin } from 'esbuild-plugin-tsconfig-paths'

✗ const tsconfigPathsPlugin = require('esbuild-plugin-tsconfig-paths')

Package is ESM-only; using require() will fail. Use dynamic import() if needed in CJS context.

default import

✓ import tsconfigPathsPlugin from 'esbuild-plugin-tsconfig-paths'

✗ import { default as tsconfigPathsPlugin } from 'esbuild-plugin-tsconfig-paths'

Package exports a named export 'tsconfigPathsPlugin' and also a default export of the same function. Both work but named export is more explicit.

TsconfigPathsPlugin (type)

✓ import type { TsconfigPathsPluginOptions } from 'esbuild-plugin-tsconfig-paths'

✗ import { TsconfigPathsPluginOptions } from 'esbuild-plugin-tsconfig-paths'

Type imports should use import type to avoid runtime side-effects. The options interface is exported for TypeScript users.

Demonstrates how to use the plugin with esbuild to resolve TypeScript path aliases during build, converting them to relative paths in the output.

import { tsconfigPathsPlugin } from 'esbuild-plugin-tsconfig-paths'; import esbuild from 'esbuild'; await esbuild.build({ entryPoints: ['src/index.ts'], outfile: 'dist/bundle.js', bundle: true, plugins: [ tsconfigPathsPlugin({ cwd: process.cwd(), tsconfig: 'tsconfig.json', filter: /\.ts$/ }) ] });

Debug

Known issues

gotchaPlugin only transforms static import statements; dynamic import() or require() calls are not modified.

fix

Use static imports for paths defined in tsconfig.json, or handle dynamic resolution separately.

affects: >=1.0.0

gotchaThe plugin's filter should be set to match .ts files only, not .tsx files, as it outputs TypeScript source with loader: 'ts'.

fix

Set filter to /\.ts$/ or adjust if you need .tsx support (not officially supported).

affects: >=1.0.0

gotchabaseUrl is assumed to be './' by default if not set in tsconfig. This may cause incorrect path resolution.

fix

Explicitly set baseUrl in tsconfig.json to the desired root directory.

affects: >=1.0.0

breakingVersion 1.0.1 to 1.0.2 changed type declarations and fixed compatibility with Go reg. No breaking API changes, but TypeScript users should update.

fix

Upgrade to v1.0.2 or later.

affects: >=1.0.1 <1.0.2

Errors

Common errors & fixes

Cannot find module 'esbuild-plugin-tsconfig-paths'

Package is not installed or incorrectly imported in a CommonJS environment.

fix

Install with 'npm install esbuild-plugin-tsconfig-paths --save-dev' and use ESM import syntax (import ... from ...). For CJS, use dynamic import: const { tsconfigPathsPlugin } = await import('esbuild-plugin-tsconfig-paths');

TypeError: tsconfigPathsPlugin is not a function

Using require() on the ESM-only package; require returns the module namespace object, not the default export.

fix

Change to ESM import or use dynamic import as described above.

Plugin tsconfigPathsPlugin: filter must be a RegExp

The filter option was passed as a string or non-RegExp value.

fix

Provide a RegExp object: e.g., filter: /\.ts$/

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/wjfei/esbuild-plugin-tsconfig-paths ↗

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