Registry / web-framework / importmap-vite-plugin

importmap-vite-plugin

library0.1.0jsnpmunverified

A Vite plugin (v0.1.0) that generates an import map JSON virtual module, enabling sharing of dependencies without duplication. It allows mapping local modules (e.g., React) to custom re-export files to support named imports from CJS packages, and external URLs (e.g., from esm.sh) to avoid bundling. Unlike Module Federation or @originjs/vite-plugin-federation, this plugin focuses solely on import maps with fine-grained control over local and remote mappings. Actively maintained on GitHub, with TypeScript definitions provided. Peer dependency on Vite (*).

web-framework http-networking

npm install importmap-vite-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · IMPORTMAP-VITE-PLU

importmap-vite-plugin

web-frameworkjavascriptv0.1.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 'importmap-vite-plugin'

✗ const importMapPlugin = require('importmap-vite-plugin')

ESM-only; package has no CommonJS export

importMap (virtual module)

✓ import importMap from 'virtual:importmap'

✗ import { importMap } from 'virtual:importmap'

Default export only; no named export. TypeScript types are provided.

Plugin options (inline)

✓ importMapPlugin({ imports: { 'react': './src/import-map/react' } })

✗ importMapPlugin({ imports: [ 'react', './src/import-map/react' ] })

The 'imports' option is an object, not an array of tuples

Configures the Vite plugin with custom local mappings, creates re-export modules for CJS packages, and mounts the generated import map in the HTML.

// vite.config.js import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; import { importMapPlugin } from 'importmap-vite-plugin'; export default defineConfig({ plugins: [ react(), importMapPlugin({ imports: { 'react': './src/import-map/react', 'react-dom': './src/import-map/react-dom', 'react/jsx-runtime': './src/import-map/react/jsx-runtime', }, }), ], }); // src/import-map/react.js export { useState, useEffect } from 'react'; export default from 'react'; // src/index.jsx import React from 'react'; import importMap from 'virtual:importmap'; const script = document.createElement('script'); script.type = 'importmap'; script.textContent = JSON.stringify(importMap); document.head.appendChild(script); ReactDOM.createRoot(document.getElementById('root')).render(<App />);

Debug

Known issues

gotchaNamed imports from CommonJS packages (like React) will fail without a local re-export file that destructures the default export

fix

Create a wrapper module (e.g., 'src/import-map/react.js') that imports the CJS default and re-exports named members

affects: >=0.1.0

deprecatedImport maps are not supported in older browsers (e.g., Safari <16.4, Chrome <89). Ensure your target browsers support import maps or use a polyfill.

fix

Use es-module-shims or another import map polyfill for older browsers

affects: >=0.1.0

gotchaThe virtual module 'virtual:importmap' is only available during development; in production, you must ensure the import map is generated and served

fix

In production builds, the plugin still works; just ensure your deployment serves the import map JSON correctly (injected via script tag)

affects: >=0.1.0

gotchaWhen mapping to external URLs (e.g., esm.sh), the plugin does NOT validate the URLs or their compatibility

fix

Test external URLs manually; ensure they export the symbols you need and are CORS-compatible

affects: >=0.1.0

Errors

Common errors & fixes

Uncaught SyntaxError: The requested module 'react' does not provide an export named 'useState'

Using named imports from a CJS module without a re-export wrapper

fix

Create a wrapper file like 'src/import-map/react.js' that re-exports named members from the CJS default export

Cannot find module 'virtual:importmap' or its corresponding type declarations

TypeScript doesn't recognize the virtual module

fix

Add a type declaration file: declare module 'virtual:importmap' { const map: { imports: Record<string, string> }; export default map; }

Error: The plugin option 'imports' should be a plain object

Passed an array instead of an object to the imports option

fix

Change imports from an array to an object with module names as keys

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/remorses/importmap-vite-plugin ↗

packagehttps://www.npmjs.com/package/importmap-vite-plugin ↗