esbuild-plugin-alias-path

2.0.2 verified Mon Apr 27 auth: no javascript

ESBuild plugin for resolving and replacing alias paths (e.g., '@foo' → './src/alias/foo.ts') with or without glob patterns. v2.0.2 supports ESBuild >= 0.14.0, ships TypeScript definitions, and is updated with fix releases on npm. Unlike tsconfig paths (which ESBuild reads automatically), this plugin enables dynamic alias replacement at build time.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/esbuild-plugin-alias-path/dist/index.mjs not supported ↓

cause Attempting to require an ESM-only package in a CommonJS context.

fix

Change to: const { aliasPath } = await import('esbuild-plugin-alias-path');

error TypeError: aliasPath is not a function ↓

cause Using named import incorrectly when the package only exports default.

fix

Import as: import aliasPath from 'esbuild-plugin-alias-path';

Warnings

gotcha Do not use 'require()' for importing the package; it is ESM-only and will throw. ↓

fix Use dynamic import: const { aliasPath } = await import('esbuild-plugin-alias-path');

gotcha When using glob pattern like '@alias/*', do not include '**' or trailing slashes in the alias key — only single asterisk is supported. ↓

fix Use '@alias/*' instead of '@alias/**/*'.

gotcha This plugin is not needed for tsconfig paths resolution; ESBuild already reads 'compilerOptions.paths' by default. ↓

fix Only use this plugin if you need runtime/dynamic alias replacement.

Install

npm install esbuild-plugin-alias-path

yarn add esbuild-plugin-alias-path

pnpm add esbuild-plugin-alias-path

Imports

aliasPath

wrong

const aliasPath = require('esbuild-plugin-alias-path')

correct

import { aliasPath } from 'esbuild-plugin-alias-path'

ESM-only package; CommonJS require will fail. Use dynamic import if needed.

aliasPath (default)
wrong
```
import { aliasPath } from 'esbuild-plugin-alias-path'
```
correct
```
import aliasPath from 'esbuild-plugin-alias-path'
```
Package exports both named and default export; both work, but default import is an alias for the named export.
AliasOption
```
import type { AliasOption } from 'esbuild-plugin-alias-path'
```
Type import available for TypeScript users to type the options object.

Quickstart

Shows how to configure aliasPath with both exact and glob alias patterns in an esbuild build script.

import { build } from 'esbuild';
import { aliasPath } from 'esbuild-plugin-alias-path';

(async () => {
  const result = await build({
    entryPoints: ['./src/main.ts'],
    bundle: true,
    outfile: './dist/main.js',
    plugins: [
      aliasPath({
        alias: {
          '@utils': './src/utils/index.ts',
          '@components/*': './src/components',
        },
      }),
    ],
  });
})();