esbuild-plugin-tsconfig-paths

1.0.2 verified Mon Apr 27 auth: no javascript

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.

Common errors

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

cause 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');

error TypeError: tsconfigPathsPlugin is not a function ↓

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

error Plugin tsconfigPathsPlugin: filter must be a RegExp ↓

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

fix

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

Warnings

gotcha Plugin 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.

gotcha The 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).

gotcha baseUrl 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.

breaking Version 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.

Install

npm install esbuild-plugin-tsconfig-paths

yarn add esbuild-plugin-tsconfig-paths

pnpm add esbuild-plugin-tsconfig-paths

Imports

tsconfigPathsPlugin

wrong

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

correct

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

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

default import
wrong
```
import { default as tsconfigPathsPlugin } from 'esbuild-plugin-tsconfig-paths'
```
correct
```
import 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)

wrong

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

correct

import type { 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.

Quickstart

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$/
    })
  ]
});