{"id":25261,"library":"esbuild-auto-path-plugin","title":"esbuild-auto-path-plugin","description":"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.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/smapiot/piral-cli-esbuild","tags":["javascript","plugin","esbuild","build","microfrontend","typescript"],"install":[{"cmd":"npm install esbuild-auto-path-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-auto-path-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-auto-path-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency - the plugin is designed to work as an esbuild plugin","package":"esbuild","optional":false}],"imports":[{"note":"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.","wrong":"const autoPathPlugin = require('esbuild-auto-path-plugin')","symbol":"autoPathPlugin","correct":"import { autoPathPlugin } from 'esbuild-auto-path-plugin'"},{"note":"Type-only import available for TypeScript users. Options include 'defaultExtensions' array of strings.","symbol":"AutoPathPluginOptions","correct":"import type { AutoPathPluginOptions } from 'esbuild-auto-path-plugin'"},{"note":"If using CommonJS, destructure the named export. The package does not export a default object.","wrong":"const autoPathPlugin = require('esbuild-auto-path-plugin').default","symbol":"autoPathPlugin (CommonJS fallback)","correct":"const { autoPathPlugin } = require('esbuild-auto-path-plugin')"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport { autoPathPlugin } from 'esbuild-auto-path-plugin';\n\nawait build({\n  entryPoints: ['src/index.ts'],\n  outdir: 'dist',\n  bundle: true,\n  plugins: [autoPathPlugin()],\n  loader: { '.png': 'file', '.svg': 'file' },\n});\n\n// After build, asset imports like:\n// import img from './icon.png';\n// will resolve to something like:\n// const img = new URL('./icon-abc123.png', import.meta.url).href;","lang":"typescript","description":"Sets up esbuild with autoPathPlugin to bundle and resolve asset paths at runtime using import.meta.url."},"warnings":[{"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.","message":"From v1.0.0, the plugin only supports ES modules. CommonJS projects may break if they rely on require() for the plugin itself.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"If you rely on the old defaults, explicitly pass defaultExtensions: ['.png', '.svg', '.jpg', '.jpeg', '.webp', '.mp4', '.mp3', '.ogg', '.wav', '.ogv', '.wasm', '.gif'].","message":"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.","severity":"deprecated","affected_versions":">=1.2.1"},{"fix":"Set format: 'esm' in esbuild build options, or avoid using this plugin with CommonJS output.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure assets you want to auto-path are loaded with loader: { '.ext': 'file' } in esbuild config.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run 'npm install esbuild-auto-path-plugin --save-dev'. If your project is CJS, use 'const { autoPathPlugin } = await import('esbuild-auto-path-plugin');'.","cause":"Package not installed, or using ESM-only package in a CommonJS project without dynamic import.","error":"Error: Cannot find module 'esbuild-auto-path-plugin'"},{"fix":"Use named import: import { autoPathPlugin } from 'esbuild-auto-path-plugin';","cause":"Improper import – likely using default import instead of named import.","error":"TypeError: esbuildAutoPathPlugin is not a function"},{"fix":"Call autoPathPlugin() in the plugins array: plugins: [autoPathPlugin()].","cause":"Passing an object instead of calling the function. The plugin export is a function that returns a plugin object.","error":"The plugin 'autoPathPlugin' is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}