Registry / devops / esbuild-plugin-path-alias

esbuild-plugin-path-alias

library1.0.7jsnpmunverified

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.

devops

npm install esbuild-plugin-path-alias

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-PAT

esbuild-plugin-path-alias

devopsjavascriptv1.0.7

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.

esbuildPluginPathAlias

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

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

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

default

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

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

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

esbuildPluginPathAlias

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

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

Namespace import works only for default export.

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'

Debug

Known issues

breakingAlias values must be absolute paths; relative paths will not be resolved correctly.

fix

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

affects: <1.0.0

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

affects: >=0.0.0

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

affects: <=1.0.7

gotchaImport 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).

affects: >=0.0.0

Errors

Common errors & fixes

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

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').

TypeError: aliasPlugin is not a function

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

fix

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

Cannot find module '@components/Header'

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

Upgrade

Version history

1.0.7latest on npm

Audit

Dependencies

esbuildrequiredpeer dependency required to function as a plugin

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/indooorsman/esbuild-plugin-path-alias ↗

packagehttps://www.npmjs.com/package/esbuild-plugin-path-alias ↗