Registry / web-framework / esbuild-auto-path-plugin

esbuild-auto-path-plugin

library1.4.0jsnpmunverified

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.

web-framework devops

npm install esbuild-auto-path-plugin

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ESBUILD-AUTO-PATH-

esbuild-auto-path-plugin

web-frameworkjavascriptv1.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

autoPathPlugin

✓ import { autoPathPlugin } from 'esbuild-auto-path-plugin'

✗ const autoPathPlugin = require('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)

✓ const { autoPathPlugin } = require('esbuild-auto-path-plugin')

✗ const autoPathPlugin = require('esbuild-auto-path-plugin').default

If using CommonJS, destructure the named export. The package does not export a default object.

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;

Debug

Known issues

breakingFrom 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.

affects: >=1.0.0

deprecatedThe 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'].

affects: >=1.2.1

gotchaThe 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.

affects: >=0.1.0

gotchaThe 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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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');'.

TypeError: esbuildAutoPathPlugin is not a function

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

fix

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

The plugin 'autoPathPlugin' is not a function

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()].

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency - the plugin is designed to work as an esbuild plugin

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/smapiot/piral-cli-esbuild ↗

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

homepagehttps://piral.io ↗