Registry / devops / esbuild-plugin-alias

esbuild-plugin-alias

library0.2.1jsnpmunverified

esbuild plugin for creating path aliases, allowing dynamic resolution of import paths based on conditions like environment variables. Version 0.2.1 is the current stable release. The plugin requires absolute file paths for aliases. It is a lightweight alternative to using esbuild's built-in `alias` or custom onResolve plugins, specifically designed for conditional aliasing. It ships TypeScript definitions and is published on npm.

devops

npm install esbuild-plugin-alias

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-ALI

esbuild-plugin-alias

devopsjavascriptv0.2.1

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.

default

✓ import alias from 'esbuild-plugin-alias'

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

The package exports a default function, not a named export. In ESM, import default; in CJS, require returns the function directly.

alias (CommonJS)

✓ const alias = require('esbuild-plugin-alias')

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

Do not destructure the require result. The module.exports is a single function.

alias (TypeScript)

✓ import alias from 'esbuild-plugin-alias'

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

TypeScript types are included, but the export is default. Named import will result in undefined.

Creates an alias for 'settings.env' resolving to a path that depends on the NODE_ENV environment variable.

import alias from 'esbuild-plugin-alias'; import esbuild from 'esbuild'; import path from 'path'; await esbuild.build({ entryPoints: ['src/app.js'], bundle: true, outfile: 'dist/out.js', plugins: [ alias({ 'settings.env': path.resolve(__dirname, 'src', `settings.${process.env.NODE_ENV ?? 'dev'}.js`), }), ], });

Debug

Known issues

breakingAlias values must be absolute file paths; relative paths will fail silently or resolve incorrectly.

fix

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

affects: all

gotchaThe plugin does not resolve relative paths starting with './' or '../'; they must be converted to absolute.

fix

Use path.resolve(__dirname, relativePath) to generate absolute path.

affects: all

deprecatedNo breaking changes reported; all versions are stable.

fix

N/A

affects: none

Errors

Common errors & fixes

Error: Could not resolve 'settings.env'

Alias value is a relative path instead of absolute.

fix

Use path.resolve() to convert the value to an absolute path.

TypeError: alias is not a function

Named import { alias } when the package exports a default function.

fix

Use default import: import alias from 'esbuild-plugin-alias' or const alias = require('esbuild-plugin-alias').

ReferenceError: __dirname is not defined in ES module scope

Using CommonJS-only __dirname in ESM context.

fix

Use import.meta.url with fileURLToPath or use path.dirname(new URL(import.meta.url).pathname).

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

esbuildrequiredpeer dependency for esbuild plugin API

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/igoradamenko/esbuild-plugin-alias ↗

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