esbuild-plugin-path-alias

1.0.7 verified Mon Apr 27 auth: no javascript

A esbuild plugin to support path aliases similar to webpack's resolve.alias. Current version 1.0.7, limited release history. It allows developers to define custom path mappings (e.g., '@' -> './app/component') so that import paths in source code can be shortened. The plugin requires esbuild as a peer dependency and expects absolute paths in alias definitions. Compared to alternatives like `esbuild-alias`, this plugin is minimal and focused, but lacks advanced features like tsconfig path resolution. It uses the `onResolve` hook and Node.js path module for resolution, and works with both ESM and CJS builds.

Common errors

error Error: esbuild-plugin-path-alias: alias path must be absolute. ↓

cause Alias value provided as relative path (e.g., './src/components').

fix

Use path.resolve() to make the alias value absolute, e.g., path.resolve(__dirname, 'src/components').

error TypeError: aliasPlugin is not a function ↓

cause Attempted to import named export { aliasPlugin } instead of default export.

fix

Use import aliasPlugin from 'esbuild-plugin-path-alias' instead of destructuring.

error Cannot find module '@components/Header' ↓

cause Alias '@' is defined but the import path uses '@components' with an extra prefix.

fix

Define alias for '@components' or ensure the import path matches exactly: import from '@/Header'.

Warnings

breaking Alias values must be absolute paths; relative paths will not be resolved correctly. ↓

fix Use path.resolve() to convert relative paths to absolute.

gotcha The plugin does not respect tsconfig 'paths' auto-resolution; you must manually define each alias. ↓

fix Consider using esbuild-plugin-tsconfig-paths if you need tsconfig-based aliases.

deprecated The package is rarely updated; the README warns that it uses `require()` internally which may affect ESM builds. ↓

fix Ensure your esbuild setup supports CJS plugins, or use an alternative that provides ESM exports.

gotcha Import paths with aliases must match exactly; trailing slashes or case sensitivity may cause resolution to fail. ↓

fix Verify alias definitions and import statements match exactly, including path separators (use forward slashes).

Install

npm install esbuild-plugin-path-alias

yarn add esbuild-plugin-path-alias

pnpm add esbuild-plugin-path-alias

Imports

esbuildPluginPathAlias

wrong

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

correct

import esbuildPluginPathAlias from 'esbuild-plugin-path-alias'

Default export; CJS require works in Node but TypeScript may need esModuleInterop.

default

wrong

const { aliasPlugin } = require('esbuild-plugin-path-alias')

correct

import aliasPlugin from 'esbuild-plugin-path-alias'

There is no named export; only default export. Using destructuring yields undefined.

esbuildPluginPathAlias

wrong

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

correct

import * as alias from 'esbuild-plugin-path-alias'
alias.default({ '@': __dirname + '/src' })

Namespace import works only for default export.

Quickstart

Shows how to set up esbuild-plugin-path-alias with two aliases, then import using the alias.

import esbuild from 'esbuild';
import aliasPlugin from 'esbuild-plugin-path-alias';
import path from 'path';

await esbuild.build({
  entryPoints: [path.resolve(__dirname, 'src/index.js')],
  bundle: true,
  outdir: 'dist',
  plugins: [
    aliasPlugin({
      '@': path.resolve(__dirname, 'src/components'),
      '#': path.resolve(__dirname, 'src/utils'),
    }),
  ],
});
// In src/index.js: import MyComponent from '@/MyComponent'