esbuild-plugin-resolve

2.0.0 verified Fri May 01 auth: no javascript maintenance

An esbuild plugin (v2.0.0, last updated 2023) that allows you to replace module import paths during bundling. It intercepts resolve calls and swaps dependencies, useful for mocking or aliasing in tests or builds. Differentiators: lightweight, no dependencies, regex-based matching. Released as v1.0.0 in 2022, with v2.0.0 switching to ES modules. Maintenance-mode with no recent commits.

Common errors

error Cannot find module 'esbuild-plugin-resolve' ↓

cause Package not installed or incorrect import path.

fix

Run 'npm install --save-dev esbuild-plugin-resolve' and use valid import syntax for your module system.

error TypeError: resolve is not a function ↓

cause Named import instead of default import (ESM).

fix

Use 'import resolve from "esbuild-plugin-resolve"' instead of 'import { resolve } from "esbuild-plugin-resolve"'.

error Error: The plugin must be an object with a name and setup function ↓

cause The resolve function was not called; plugin array received the raw import.

fix

Call resolve() with options: plugins: [resolve({ test: 'foo' })].

Warnings

breaking v2.0.0 switched to ES modules; CommonJS require() no longer works. ↓

fix Use ESM imports (import resolve from ...) or downgrade to v1.x.

deprecated The 'replaceWith' option is not documented in v2.0.0; the API changed from v1.x to v2.0.0. ↓

fix Check plugin API: in v2.0.0, options might be different. Refer to the repository's usage examples.

gotcha The 'test' option is treated as a regex pattern without escaping; special regex characters can cause unexpected matches. ↓

fix Escape regex-special characters in the module name, e.g., use 'lodash\.merge' instead of 'lodash.merge'.

gotcha If the original module has no default export, the plugin may not resolve correctly (fixed in v1.1.0 but verify). ↓

fix Upgrade to v1.1.0 or later.

Install

npm install esbuild-plugin-resolve

yarn add esbuild-plugin-resolve

pnpm add esbuild-plugin-resolve

Imports

resolve

wrong

const resolve = require('esbuild-plugin-resolve')

correct

import resolve from 'esbuild-plugin-resolve'

Default export; v2.0.0 is ESM-only, require() fails.

resolve

wrong

import { resolve } from 'esbuild-plugin-resolve'

correct

import * as pkg from 'esbuild-plugin-resolve'; const resolve = pkg.default

It is a default export, not a named export. Named import will be undefined.

resolve (as plugin function)
wrong
```
plugins: [resolve({ test: 'foo' })]
```
correct
```
plugins: [resolve({ test: 'foo' })]
```
Usage is straightforward; no wrong pattern beyond the import. The resolve function returns an esbuild plugin object.

Quickstart

Shows how to bundle with esbuild and replace 'lodash' imports with 'lodash-es' using the plugin.

import esbuild from 'esbuild';
import resolve from 'esbuild-plugin-resolve';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [resolve({
    test: 'lodash',
    replaceWith: 'lodash-es'
  })]
});