Registry / devops / rollup-plugin-import-map

rollup-plugin-import-map

library3.0.0jsnpmunverified

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.

devops

npm install rollup-plugin-import-map

github ↗package ↗

INSTALL

IMPORT

SIG · ROLLUP-PLUGIN-IMPO

rollup-plugin-import-map

devopsjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

importMapPlugin

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

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

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

rollup

✓ import { rollup } from 'rollup'

✗ const rollup = require('rollup')

Rollup v3 is ESM-only; use ESM imports.

default export

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

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

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

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

Debug

Known issues

breakingv3 to v4 transitions to a required base URL argument, changing plugin signature.

fix

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

affects: >=4.0.0-next.1

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

affects: >=3.0.0 <4.0.0

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

fix

Update plugin configuration to follow new import map JSON structure.

affects: >=2.0.0 <3.0.0

gotchaUsing default export as named import will result in undefined at runtime.

fix

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

affects: >=3.0.0

gotchaThe 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://...).

affects: >=2.0.0

Errors

Common errors & fixes

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

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.

TypeError: importMapPlugin is not a function

Named import instead of default import.

fix

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

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

In v4, first argument must be a base URL.

fix

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

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

@import-maps/generaterequiredCore engine for resolving import map mappings

rolluprequiredPeer dependency to integrate with Rollup (v2 or v3 depending on plugin version)

Agent activity

5 hits · last 30 days

node

Resources

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

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