esbuild-plugin-alias's Introduction

esbuild-plugin-alias

esbuild plugin for path aliases.

Rationale

Sometimes it's useful to have dynamic imports that resolves into different files depending on some conditions (e.g. env variables).

Installation

npm install --save-dev esbuild-plugin-alias

Usage

Define plugin in the plugins section of esbuild config like this:

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

esbuild.build({
  // ...
  plugins: [
    alias({
      'imported-path': '/home/user/lib/src/resolved-path',
    }),
  ],
})

Note: esbuild requires resolved paths to be absolute. So, make sure that values in plugin's config object are absolute paths.

If you need to find a path to an installed dep, you may use require.resolve. E.g.:

alias({
  'react-dom': process.env.NODE_ENV === 'dev' 
    ? require.resolve('@hot-loader/react-dom')
    : require.resolve('react-dom'),
}),

Example

Having this input file:

// src/app.js
import settings from 'settings.env';

console.log(settings);

And esbuild config like this:

// config/build.js
const path = require('path');
const esbuild = require('esbuild');
const alias = require('esbuild-plugin-alias');

esbuild.build({
  entryPoints: ['in.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [
    alias({
      'settings.env': path.resolve(__dirname, `../src/settings.${process.env.NODE_ENV}.js`),
    }),
  ],
}).catch(err => process.exit(1));