importmap-vite-plugin

0.1.0 verified Mon Apr 27 auth: no javascript

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 (*).

Common errors

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

cause 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

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

cause 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 Error: The plugin option 'imports' should be a plain object ↓

cause 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

Warnings

gotcha Named 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

deprecated Import 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

gotcha The 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)

gotcha When 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

Install

npm install importmap-vite-plugin

yarn add importmap-vite-plugin

pnpm add importmap-vite-plugin

Imports

importMapPlugin

wrong

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

correct

import { importMapPlugin } from 'importmap-vite-plugin'

ESM-only; package has no CommonJS export

importMap (virtual module)
wrong
```
import { importMap } from 'virtual:importmap'
```
correct
```
import importMap from 'virtual:importmap'
```
Default export only; no named export. TypeScript types are provided.

Plugin options (inline)

wrong

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

correct

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

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

Quickstart

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