{"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,"search_vec":"'1.4.0':31 '16':38 'altern':50 'asset':12,68,77 'auto':3 'automat':10 'build':55,88 'build-tim':54 'cli':47 'configur':59 'determin':83 'differ':73 'ecosystem':48 'elimin':22 'enabl':62 'esbuild':2,7,87 'esbuild-auto-path-plugin':1 'file':19 'fix':27 'frontend':64 'import':17,78 'javascript':18,85 'latest':32 'maintain':41 'micro':63 'microfrontend':89 'need':24 'node':37 'part':43 'path':4,13,29,58,74,84 'piral':46 'plugin':5,8,61,86 'public':28,57 'relat':14 'requir':53 'resolv':11 'rewrit':76 'runtim':21,82 'runtime-determin':81 'serv':70 'setup':65 'ship':33 'solut':51 'support':36 'time':56 'type':35 'typescript':34,90 'unlik':49 'use':80 'version':30","created_at":"2026-05-01T13:43:50.817217+00:00","updated_at":"2026-05-01T13:43:50.817217+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://piral.io","github":"https://github.com/smapiot/piral-cli-esbuild","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/esbuild-auto-path-plugin","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-05-01","next_check":"2026-07-30","install_tag":null}}