esbuild-plugin-import-map

2.1.0 verified Fri May 01 auth: no javascript

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.

Common errors

error Error: Cannot find module 'esbuild-plugin-import-map' ↓

cause ESM package required via require() in CommonJS context

fix

Use import syntax in an ESM module, or set type: 'module' in package.json.

error TypeError: plugin is not a function ↓

cause Default import used incorrectly; forgot to call plugin() as a function?

fix

Use plugin = require('esbuild-plugin-import-map').default or import plugin from '...' and call plugin() when adding to esbuild plugins array.

error Error: Invalid import map: unexpected token at position 0 ↓

cause Import map loaded from a file that is not valid JSON (e.g., JSON with comments)

fix

Strip comments or ensure the file is pure JSON before loading.

Warnings

breaking 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. ↓

fix Update .load() calls to pass a base URL string as the first argument, e.g., .load('https://example.com')

breaking 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. ↓

fix Test all import map entries against the new spec; adjust mappings as needed.

deprecated 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. ↓

fix Migrate to v3.0.0-next when it becomes stable; for now, stick with v2.1.0 if you need reliability.

gotcha The plugin only processes import map mappings for ESM imports (import statements, dynamic import()). CJS require() calls are not transformed. ↓

fix Ensure all imports you want mapped are ESM-style. Use esbuild's ESM output format.

gotcha Import maps must be pure JSON; comments or trailing commas will cause parse errors. ↓

fix Validate import map JSON with JSON.parse() before passing to plugin.

Install

npm install esbuild-plugin-import-map

yarn add esbuild-plugin-import-map

pnpm add esbuild-plugin-import-map

Imports

default

wrong

const plugin = require('esbuild-plugin-import-map')

correct

import plugin from 'esbuild-plugin-import-map'

ESM-only; require() fails in Node ESM context.

importMapPlugin

import { importMapPlugin } from 'esbuild-plugin-import-map'

Named export also available; same as default.

loadImportMap

wrong

const { loadImportMap } = require('esbuild-plugin-import-map')

correct

import { loadImportMap } from 'esbuild-plugin-import-map'

Utility to load import map from file; ESM only.

Quickstart

Bundles an entry point, applying import map resolutions ahead of time using the default plugin instance.

import esbuild from 'esbuild';
import plugin from 'esbuild-plugin-import-map';

esbuild.build({
  entryPoints: ['src/app.js'],
  bundle: true,
  outfile: 'dist/app.js',
  plugins: [plugin()],
  define: {
    'process.env.IMPORT_MAP_URL': JSON.stringify('https://example.com/import-map.json')
  }
}).catch(() => process.exit(1));