{"id":25356,"library":"esbuild-plugin-import-map","title":"esbuild-plugin-import-map","description":"ESbuild plugin that applies import map mappings to ESM imports at build time, replacing runtime import map resolution. Version 2.1.0 (stable) is the latest release; v3.0.0 is in development with breaking changes. Key differentiators: works ahead of time, reducing runtime overhead; supports reading import maps from filesystem; integrates seamlessly with esbuild's plugin system. Alternative: using runtime import maps (native browser feature) but requires browser support and adds latency.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/trygve-lie/esbuild-plugin-import-map","tags":["javascript","ESBuild","Import","Map","ESM","Modules","ECMAScript"],"install":[{"cmd":"npm install esbuild-plugin-import-map","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-import-map","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-import-map","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only; require() fails in Node ESM context.","wrong":"const plugin = require('esbuild-plugin-import-map')","symbol":"default","correct":"import plugin from 'esbuild-plugin-import-map'"},{"note":"Named export also available; same as default.","wrong":null,"symbol":"importMapPlugin","correct":"import { importMapPlugin } from 'esbuild-plugin-import-map'"},{"note":"Utility to load import map from file; ESM only.","wrong":"const { loadImportMap } = require('esbuild-plugin-import-map')","symbol":"loadImportMap","correct":"import { loadImportMap } from 'esbuild-plugin-import-map'"}],"quickstart":{"code":"import esbuild from 'esbuild';\nimport plugin from 'esbuild-plugin-import-map';\n\nesbuild.build({\n  entryPoints: ['src/app.js'],\n  bundle: true,\n  outfile: 'dist/app.js',\n  plugins: [plugin()],\n  define: {\n    'process.env.IMPORT_MAP_URL': JSON.stringify('https://example.com/import-map.json')\n  }\n}).catch(() => process.exit(1));","lang":"javascript","description":"Bundles an entry point, applying import map resolutions ahead of time using the default plugin instance."},"warnings":[{"fix":"Update .load() calls to pass a base URL string as the first argument, e.g., .load('https://example.com')","message":"v3.0.0-next changes the first argument to .load() from an options object to a base URL (string). This breaks any code that calls .load() with an object.","severity":"breaking","affected_versions":">=3.0.0-next.1"},{"fix":"Test all import map entries against the new spec; adjust mappings as needed.","message":"v3.0.0-next is spec-compliant but breaks existing import map mappings. Mappings that previously worked may not resolve correctly under the new spec.","severity":"breaking","affected_versions":">=3.0.0-next.1"},{"fix":"Migrate to v3.0.0-next when it becomes stable; for now, stick with v2.1.0 if you need reliability.","message":"v2.x is stable but v3.0.0 is in development and will replace it. No official deprecation notice yet, but new features and fixes go to v3.","severity":"deprecated","affected_versions":"2.x"},{"fix":"Ensure all imports you want mapped are ESM-style. Use esbuild's ESM output format.","message":"The plugin only processes import map mappings for ESM imports (import statements, dynamic import()). CJS require() calls are not transformed.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Validate import map JSON with JSON.parse() before passing to plugin.","message":"Import maps must be pure JSON; comments or trailing commas will cause parse errors.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use import syntax in an ESM module, or set type: 'module' in package.json.","cause":"ESM package required via require() in CommonJS context","error":"Error: Cannot find module 'esbuild-plugin-import-map'"},{"fix":"Use plugin = require('esbuild-plugin-import-map').default or import plugin from '...' and call plugin() when adding to esbuild plugins array.","cause":"Default import used incorrectly; forgot to call plugin() as a function?","error":"TypeError: plugin is not a function"},{"fix":"Strip comments or ensure the file is pure JSON before loading.","cause":"Import map loaded from a file that is not valid JSON (e.g., JSON with comments)","error":"Error: Invalid import map: unexpected token at position 0"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}