{"id":22078,"library":"rollup-plugin-import-map","title":"rollup-plugin-import-map","description":"A Rollup plugin to apply import map mappings during the build process, enabling module resolution according to the WICG import map specification. Current stable version is v3.0.0 (ESM-only, supports Rollup 3). There is also a v4.0.0-next.1 pre-release with full import map support but significant API changes. The plugin wraps the `@import-maps/generate` library to resolve bare specifiers to URLs defined in an import map JSON. It is one of few Rollup plugins that implement import map resolution, distinct from `@rollup/plugin-node-resolve` which resolves to node_modules. Release cadence has been low; breaking changes between major versions require migration attention.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/trygve-lie/rollup-plugin-import-map","tags":["javascript","Rollup","Import","Map","ESM","Modules","ECMAScript"],"install":[{"cmd":"npm install rollup-plugin-import-map","lang":"bash","label":"npm"},{"cmd":"yarn add rollup-plugin-import-map","lang":"bash","label":"yarn"},{"cmd":"pnpm add rollup-plugin-import-map","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core engine for resolving import map mappings","package":"@import-maps/generate","optional":false},{"reason":"Peer dependency to integrate with Rollup (v2 or v3 depending on plugin version)","package":"rollup","optional":false}],"imports":[{"note":"Since v3, the package is ESM-only, so CommonJS require will fail.","wrong":"const importMapPlugin = require('rollup-plugin-import-map')","symbol":"importMapPlugin","correct":"import importMapPlugin from 'rollup-plugin-import-map'"},{"note":"Rollup v3 is ESM-only; use ESM imports.","wrong":"const rollup = require('rollup')","symbol":"rollup","correct":"import { rollup } from 'rollup'"},{"note":"The plugin is exported as default, not a named export.","wrong":"import { importMapPlugin } from 'rollup-plugin-import-map'","symbol":"default export","correct":"import importMapPlugin from 'rollup-plugin-import-map'"}],"quickstart":{"code":"import importMapPlugin from 'rollup-plugin-import-map';\nimport { rollup } from 'rollup';\n\nconst build = await rollup({\n  input: 'src/index.js',\n  plugins: [\n    importMapPlugin({\n      imports: {\n        'lodash': 'https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.js'\n      }\n    })\n  ]\n});\n\nawait build.write({ dir: 'dist', format: 'es' });\nconsole.log('Build complete');","lang":"javascript","description":"Configures Rollup with import-map plugin to map 'lodash' to a CDN URL, then bundles to 'dist'."},"warnings":[{"fix":"Provide a base URL as first argument: importMapPlugin(baseUrl, ...options)","message":"v3 to v4 transitions to a required base URL argument, changing plugin signature.","severity":"breaking","affected_versions":">=4.0.0-next.1"},{"fix":"Use ESM imports and upgrade to Rollup 3. If CJS needed, stay on v2.","message":"v2 to v3: Dropped CommonJS support and Rollup 2, now ESM-only and Rollup 3+.","severity":"breaking","affected_versions":">=3.0.0 <4.0.0"},{"fix":"Update plugin configuration to follow new import map JSON structure.","message":"v2: Complete rewrite to align with WICG import map spec; previous API (v1) removed.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Use default import, not named: import importMap from '...'","message":"Using default export as named import will result in undefined at runtime.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Ensure all values in import map imports are fully qualified URLs (e.g., https://...).","message":"The plugin does not resolve relative paths in the import map; all mappings must be absolute URLs.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Switch to ESM: set \"type\": \"module\" in package.json or use .mjs extension, then use import.","cause":"Using CommonJS require() on ESM-only package (v3+).","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"},{"fix":"Use default import: import importMapPlugin from 'rollup-plugin-import-map'","cause":"Named import instead of default import.","error":"TypeError: importMapPlugin is not a function"},{"fix":"Call as importMapPlugin(new URL('https://example.com'), {...})","cause":"In v4, first argument must be a base URL.","error":"Error: The plugin requires a base URL as string or URL object.","affected_versions":">=4.0.0-next.1"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}