esbuild-import-plugin

0.0.15 verified Fri May 01 auth: no javascript

An esbuild plugin that transforms import statements for enhanced module resolution and aliasing. Version 0.0.15, last updated in 2022, with sporadic maintenance. It provides a simple API to customize how imports are resolved during bundling, supporting option overrides for prefixes and base directories. Unlike more complex solutions like alias plugins, this plugin focuses on lightweight import manipulation without requiring extensive configuration. Its release cadence is low, with only a few versions published.

Common errors

error Error: Cannot find module 'esbuild-import-plugin' ↓

cause Package not installed or incorrectly required.

fix

Run npm install esbuild-import-plugin or yarn add esbuild-import-plugin.

error TypeError: importPlugin is not a function ↓

cause Using destructured import instead of default import.

fix

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

error Error: Build failed with 1 error: error: Could not resolve '@components/Button' ↓

cause The plugin's import resolution did not match the configured prefix or baseDir.

fix

Ensure importPlugin is called with options that map '@' to the correct base directory, e.g., importPlugin({ prefix: '@', baseDir: './src' }).

Warnings

gotcha Plugin may not resolve imports with custom prefixes correctly if options are not provided. ↓

fix Always call importPlugin() with explicit options matching your project structure.

deprecated Package has not been updated since 2022; may not work with newer esbuild versions. ↓

fix Consider using esbuild's built-in alias support or more maintained plugins like esbuild-plugin-alias.

gotcha Import resolution fails silently if prefix or baseDir options are mismatched, leading to runtime errors. ↓

fix Verify that baseDir is absolute or relative to project root, and prefix matches the import strings.

Install

npm install esbuild-import-plugin

yarn add esbuild-import-plugin

pnpm add esbuild-import-plugin

Imports

default (importPlugin)
wrong
```
const importPlugin = require('esbuild-import-plugin')
```
correct
```
import importPlugin from 'esbuild-import-plugin'
```
Package does not export named members; the default export is a function. CJS require works but breaks in ESM environments.
importPlugin function
wrong
```
const { importPlugin } = require('esbuild-import-plugin')
```
correct
```
import importPlugin from 'esbuild-import-plugin'
```
Destructuring from require will yield undefined because there is no named export.
Options (optional)
wrong
```
importPlugin({ prefix: '/@', basedir: './src' })
```
correct
```
importPlugin({ prefix: '@', baseDir: './src' })
```
Options are passed as object to default function; property names are 'prefix' and 'baseDir' (camelCase). Incorrect casing or extra slash will cause mismatched resolution.

Quickstart

Shows how to use esbuild-import-plugin with esbuild to bundle an entry point, applying the import plugin with default settings.

import esbuild from 'esbuild';
import importPlugin from 'esbuild-import-plugin';

await esbuild.build({
  entryPoints: ['./src/index.js'],
  bundle: true,
  outfile: './dist/app.js',
  loader: { '.js': 'jsx' },
  sourcemap: true,
  target: ['chrome58', 'firefox57', 'safari11', 'edge16'],
  define: { 'process.env.NODE_ENV': '"development"' },
  plugins: [importPlugin()],
});
console.log('Build complete.');