esbuild-auto-path-plugin

1.4.0 verified Fri May 01 auth: no javascript

An esbuild plugin that automatically resolves asset paths relative to the importing JavaScript file at runtime, eliminating the need for a fixed public path. Version 1.4.0 (latest) ships TypeScript types, supports Node >=16, and is maintained as part of the Piral CLI ecosystem. Unlike alternative solutions that require build-time public path configuration, this plugin enables micro frontend setups where each asset is served from a different path by rewriting asset imports to use runtime-determined paths.

Common errors

error Error: Cannot find module 'esbuild-auto-path-plugin' ↓

cause Package not installed, or using ESM-only package in a CommonJS project without dynamic import.

fix

Run 'npm install esbuild-auto-path-plugin --save-dev'. If your project is CJS, use 'const { autoPathPlugin } = await import('esbuild-auto-path-plugin');'.

error TypeError: esbuildAutoPathPlugin is not a function ↓

cause Improper import – likely using default import instead of named import.

fix

Use named import: import { autoPathPlugin } from 'esbuild-auto-path-plugin';

error The plugin 'autoPathPlugin' is not a function ↓

cause Passing an object instead of calling the function. The plugin export is a function that returns a plugin object.

fix

Call autoPathPlugin() in the plugins array: plugins: [autoPathPlugin()].

Warnings

breaking From v1.0.0, the plugin only supports ES modules. CommonJS projects may break if they rely on require() for the plugin itself. ↓

fix Switch project to ESM (type: 'module' in package.json) or use dynamic import. Alternatively, use older version 0.15.x if CJS support is required.

deprecated The default extension list changed in v1.2.1 – web fonts like .woff, .woff2, .ttf, .eot were added. Projects using custom loader without specifying defaultExtensions may get unexpected behavior. ↓

fix If you rely on the old defaults, explicitly pass defaultExtensions: ['.png', '.svg', '.jpg', '.jpeg', '.webp', '.mp4', '.mp3', '.ogg', '.wav', '.ogv', '.wasm', '.gif'].

gotcha The plugin relies on import.meta.url which requires the output format to be 'esm'. If esbuild output format is 'cjs', the auto path resolution will not work correctly. ↓

fix Set format: 'esm' in esbuild build options, or avoid using this plugin with CommonJS output.

gotcha The plugin only transforms asset imports that are handled by the 'file' loader in esbuild. Custom loaders (e.g., 'binary', 'dataurl') will not be auto-pathed. ↓

fix Ensure assets you want to auto-path are loaded with loader: { '.ext': 'file' } in esbuild config.

Install

npm install esbuild-auto-path-plugin

yarn add esbuild-auto-path-plugin

pnpm add esbuild-auto-path-plugin

Imports

autoPathPlugin
wrong
```
const autoPathPlugin = require('esbuild-auto-path-plugin')
```
correct
```
import { autoPathPlugin } from 'esbuild-auto-path-plugin'
```
The package is ESM-only; default import is not available. Use named import. CommonJS require may not work in newer versions if resolution is ESM-only.
AutoPathPluginOptions
```
import type { AutoPathPluginOptions } from 'esbuild-auto-path-plugin'
```
Type-only import available for TypeScript users. Options include 'defaultExtensions' array of strings.
autoPathPlugin (CommonJS fallback)
wrong
```
const autoPathPlugin = require('esbuild-auto-path-plugin').default
```
correct
```
const { autoPathPlugin } = require('esbuild-auto-path-plugin')
```
If using CommonJS, destructure the named export. The package does not export a default object.

Quickstart

Sets up esbuild with autoPathPlugin to bundle and resolve asset paths at runtime using import.meta.url.

import { build } from 'esbuild';
import { autoPathPlugin } from 'esbuild-auto-path-plugin';

await build({
  entryPoints: ['src/index.ts'],
  outdir: 'dist',
  bundle: true,
  plugins: [autoPathPlugin()],
  loader: { '.png': 'file', '.svg': 'file' },
});

// After build, asset imports like:
// import img from './icon.png';
// will resolve to something like:
// const img = new URL('./icon-abc123.png', import.meta.url).href;