babel-plugin-import-map

1.0.0 verified Sat Apr 25 auth: no javascript

A Babel plugin to apply import map mappings to ECMAScript modules ahead of time. Current stable version is 1.0.0. This plugin allows transforming bare import specifiers (e.g., 'lit-html') to absolute URLs (e.g., CDN URLs) at build time, based on one or more import map files. It supports loading import maps from JSON files or plain objects, and can merge multiple maps. Unlike runtime import map polyfills, this works purely at the build level, making it suitable for production bundles. Once loaded, the plugin replaces import specifiers statically during Babel transpilation.

Common errors

error TypeError: plugin.load is not a function ↓

cause Using default import instead of namespace import.

fix

import * as plugin from 'babel-plugin-import-map'

error Error: Could not find import map file: source/import-map.json ↓

cause File path is relative to current working directory, not Babel config location.

fix

Use absolute path or path relative to process.cwd()

error TypeError: Cannot read properties of undefined (reading 'imports') ↓

cause Passing an object without 'imports' key or empty object.

fix

Ensure import map object has 'imports' key.

Warnings

gotcha Import specifiers already mapped are replaced; last mapping in array wins. ↓

fix Ensure correct order when passing multiple maps.

gotcha The plugin does not validate import map JSON; malformed maps cause runtime errors. ↓

fix Validate import map JSON before loading.

gotcha The plugin only transforms static import/export statements, not dynamic import(). ↓

fix Use a separate plugin or runtime polyfill for dynamic imports.

Install

npm install babel-plugin-import-map

yarn add babel-plugin-import-map

pnpm add babel-plugin-import-map

Imports

plugin

wrong

import plugin from 'babel-plugin-import-map'

correct

import * as plugin from 'babel-plugin-import-map'

This package uses a namespace import; default import does not work.

plugin.load()
wrong
```
plugin.load({imports: {'lit-html': 'https://cdn.example.com/lit-html.js'}})
```
correct
```
plugin.load('./import-map.json')
```
You can pass a string path or an object; wrong example is actually correct, but a common mistake is to forget the './' relative path.
plugin.plugin()
wrong
```
plugin()
```
correct
```
plugin.plugin()
```
The plugin function is a method on the imported namespace, not the default export itself.
plugin.clear()
wrong
```
plugin.clear
```
correct
```
plugin.clear()
```
clear() is a method that must be called; omitting parentheses is a common mistake.

Quickstart

Shows how to load an import map file and apply the plugin in a Babel configuration to transform bare ESM imports.

import * as plugin from 'babel-plugin-import-map';

plugin.load('import-map.json');

export default {
  presets: [
    ['@babel/preset-env', { modules: false }]
  ],
  plugins: [
    plugin.plugin()
  ]
};