rollup-plugin-import-map

3.0.0 verified Mon Apr 27 auth: no javascript

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.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using CommonJS require() on ESM-only package (v3+).

fix

Switch to ESM: set "type": "module" in package.json or use .mjs extension, then use import.

error TypeError: importMapPlugin is not a function ↓

cause Named import instead of default import.

fix

Use default import: import importMapPlugin from 'rollup-plugin-import-map'

error Error: The plugin requires a base URL as string or URL object. ↓

cause In v4, first argument must be a base URL.

fix

Call as importMapPlugin(new URL('https://example.com'), {...})

Warnings

breaking v3 to v4 transitions to a required base URL argument, changing plugin signature. ↓

fix Provide a base URL as first argument: importMapPlugin(baseUrl, ...options)

breaking v2 to v3: Dropped CommonJS support and Rollup 2, now ESM-only and Rollup 3+. ↓

fix Use ESM imports and upgrade to Rollup 3. If CJS needed, stay on v2.

breaking v2: Complete rewrite to align with WICG import map spec; previous API (v1) removed. ↓

fix Update plugin configuration to follow new import map JSON structure.

gotcha Using default export as named import will result in undefined at runtime. ↓

fix Use default import, not named: import importMap from '...'

gotcha The plugin does not resolve relative paths in the import map; all mappings must be absolute URLs. ↓

fix Ensure all values in import map imports are fully qualified URLs (e.g., https://...).

Install

npm install rollup-plugin-import-map

yarn add rollup-plugin-import-map

pnpm add rollup-plugin-import-map

Imports

importMapPlugin

wrong

const importMapPlugin = require('rollup-plugin-import-map')

correct

import importMapPlugin from 'rollup-plugin-import-map'

Since v3, the package is ESM-only, so CommonJS require will fail.

rollup

wrong

const rollup = require('rollup')

correct

import { rollup } from 'rollup'

Rollup v3 is ESM-only; use ESM imports.

default export

wrong

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

correct

import importMapPlugin from 'rollup-plugin-import-map'

The plugin is exported as default, not a named export.

Quickstart

Configures Rollup with import-map plugin to map 'lodash' to a CDN URL, then bundles to 'dist'.

import importMapPlugin from 'rollup-plugin-import-map';
import { rollup } from 'rollup';

const build = await rollup({
  input: 'src/index.js',
  plugins: [
    importMapPlugin({
      imports: {
        'lodash': 'https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.js'
      }
    })
  ]
});

await build.write({ dir: 'dist', format: 'es' });
console.log('Build complete');