{"id":21281,"library":"esbuild-plugin-tsconfig-paths","title":"esbuild-plugin-tsconfig-paths","description":"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.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/wjfei/esbuild-plugin-tsconfig-paths","tags":["javascript","typescript"],"install":[{"cmd":"npm install esbuild-plugin-tsconfig-paths","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-tsconfig-paths","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-tsconfig-paths","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package is ESM-only; using require() will fail. Use dynamic import() if needed in CJS context.","wrong":"const tsconfigPathsPlugin = require('esbuild-plugin-tsconfig-paths')","symbol":"tsconfigPathsPlugin","correct":"import { tsconfigPathsPlugin } from 'esbuild-plugin-tsconfig-paths'"},{"note":"Package exports a named export 'tsconfigPathsPlugin' and also a default export of the same function. Both work but named export is more explicit.","wrong":"import { default as tsconfigPathsPlugin } from 'esbuild-plugin-tsconfig-paths'","symbol":"default import","correct":"import tsconfigPathsPlugin from 'esbuild-plugin-tsconfig-paths'"},{"note":"Type imports should use import type to avoid runtime side-effects. The options interface is exported for TypeScript users.","wrong":"import { TsconfigPathsPluginOptions } from 'esbuild-plugin-tsconfig-paths'","symbol":"TsconfigPathsPlugin (type)","correct":"import type { TsconfigPathsPluginOptions } from 'esbuild-plugin-tsconfig-paths'"}],"quickstart":{"code":"import { tsconfigPathsPlugin } from 'esbuild-plugin-tsconfig-paths';\nimport esbuild from 'esbuild';\n\nawait esbuild.build({\n  entryPoints: ['src/index.ts'],\n  outfile: 'dist/bundle.js',\n  bundle: true,\n  plugins: [\n    tsconfigPathsPlugin({\n      cwd: process.cwd(),\n      tsconfig: 'tsconfig.json',\n      filter: /\\.ts$/\n    })\n  ]\n});","lang":"typescript","description":"Demonstrates how to use the plugin with esbuild to resolve TypeScript path aliases during build, converting them to relative paths in the output."},"warnings":[{"fix":"Use static imports for paths defined in tsconfig.json, or handle dynamic resolution separately.","message":"Plugin only transforms static import statements; dynamic import() or require() calls are not modified.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set filter to /\\.ts$/ or adjust if you need .tsx support (not officially supported).","message":"The plugin's filter should be set to match .ts files only, not .tsx files, as it outputs TypeScript source with loader: 'ts'.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Explicitly set baseUrl in tsconfig.json to the desired root directory.","message":"baseUrl is assumed to be './' by default if not set in tsconfig. This may cause incorrect path resolution.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to v1.0.2 or later.","message":"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.","severity":"breaking","affected_versions":">=1.0.1 <1.0.2"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"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');","cause":"Package is not installed or incorrectly imported in a CommonJS environment.","error":"Cannot find module 'esbuild-plugin-tsconfig-paths'"},{"fix":"Change to ESM import or use dynamic import as described above.","cause":"Using require() on the ESM-only package; require returns the module namespace object, not the default export.","error":"TypeError: tsconfigPathsPlugin is not a function"},{"fix":"Provide a RegExp object: e.g., filter: /\\.ts$/","cause":"The filter option was passed as a string or non-RegExp value.","error":"Plugin tsconfigPathsPlugin: filter must be a RegExp"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}