{"id":19074,"library":"babel-plugin-import-map","title":"babel-plugin-import-map","description":"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.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/trygve-lie/babel-plugin-import-map","tags":["javascript","Babel","Import","Map","ESM","Modules","ECMAScript"],"install":[{"cmd":"npm install babel-plugin-import-map","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-import-map","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-import-map","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package uses a namespace import; default import does not work.","wrong":"import plugin from 'babel-plugin-import-map'","symbol":"plugin","correct":"import * as plugin from 'babel-plugin-import-map'"},{"note":"You can pass a string path or an object; wrong example is actually correct, but a common mistake is to forget the './' relative path.","wrong":"plugin.load({imports: {'lit-html': 'https://cdn.example.com/lit-html.js'}})","symbol":"plugin.load()","correct":"plugin.load('./import-map.json')"},{"note":"The plugin function is a method on the imported namespace, not the default export itself.","wrong":"plugin()","symbol":"plugin.plugin()","correct":"plugin.plugin()"},{"note":"clear() is a method that must be called; omitting parentheses is a common mistake.","wrong":"plugin.clear","symbol":"plugin.clear()","correct":"plugin.clear()"}],"quickstart":{"code":"import * as plugin from 'babel-plugin-import-map';\n\nplugin.load('import-map.json');\n\nexport default {\n  presets: [\n    ['@babel/preset-env', { modules: false }]\n  ],\n  plugins: [\n    plugin.plugin()\n  ]\n};","lang":"javascript","description":"Shows how to load an import map file and apply the plugin in a Babel configuration to transform bare ESM imports."},"warnings":[{"fix":"Ensure correct order when passing multiple maps.","message":"Import specifiers already mapped are replaced; last mapping in array wins.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Validate import map JSON before loading.","message":"The plugin does not validate import map JSON; malformed maps cause runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use a separate plugin or runtime polyfill for dynamic imports.","message":"The plugin only transforms static import/export statements, not dynamic import().","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"import * as plugin from 'babel-plugin-import-map'","cause":"Using default import instead of namespace import.","error":"TypeError: plugin.load is not a function"},{"fix":"Use absolute path or path relative to process.cwd()","cause":"File path is relative to current working directory, not Babel config location.","error":"Error: Could not find import map file: source/import-map.json"},{"fix":"Ensure import map object has 'imports' key.","cause":"Passing an object without 'imports' key or empty object.","error":"TypeError: Cannot read properties of undefined (reading 'imports')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}