Registry / web-framework / esbuild-plugin-import-map

esbuild-plugin-import-map

library2.1.0jsnpmunverified

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.

web-framework

npm install esbuild-plugin-import-map

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-IMP

esbuild-plugin-import-map

web-frameworkjavascriptv2.1.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.

default

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

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

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

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

Utility to load import map from file; ESM only.

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

Debug

Known issues

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

affects: >=3.0.0-next.1

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

affects: >=3.0.0-next.1

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

affects: 2.x

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

affects: >=2.0.0

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

affects: >=2.0.0

Errors

Common errors & fixes

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

ESM package required via require() in CommonJS context

fix

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

TypeError: plugin is not a function

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: Invalid import map: unexpected token at position 0

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.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/trygve-lie/esbuild-plugin-import-map ↗

packagehttps://www.npmjs.com/package/esbuild-plugin-import-map ↗