vite-import-maps

0.2.6 verified Mon Apr 27 auth: no javascript

Vite plugin that generates and manages browser import maps for shared dependencies in Vite applications, targeting micro-frontends, plugin systems, and runtime ESM loading. Current stable version is 0.2.6, with monthly patch releases. Key differentiators: supports CommonJS modules via static analysis, injects import map directly into HTML or emits as a standalone file, provides Subresource Integrity (SRI) hashes, and handles both npm packages and local entry modules. Requires Vite >=6.0.0, rollup >=4.0.0, or rolldown >=1.0.0-rc.0. Renamed from 'vite-plugin-native-import-maps' in v0.2.0.

Common errors

error Error: Cannot find module 'vite-plugin-native-import-maps' ↓

cause Package was renamed to 'vite-import-maps' in v0.2.0.

fix

Run 'npm install vite-import-maps --save-dev' and update imports to use 'vite-import-maps'.

error TypeError: vitePluginNativeImportMaps is not a function ↓

cause Export renamed to 'viteImportMaps' in v0.2.0.

fix

Change import to '{ viteImportMaps }' from 'vite-import-maps'.

error Error: Unexpected token on import map JSON (e.g., missing quotes) ↓

cause Improperly formatted import map entries; likely a custom entry with invalid JSON.

fix

Ensure entries in the 'imports' array are valid strings or objects with 'name' and 'entry' properties.

Warnings

breaking In v0.2.0, the plugin was renamed from 'vite-plugin-native-import-maps' to 'vite-import-maps' and the main export was renamed from 'vitePluginNativeImportMaps' to 'viteImportMaps'. ↓

fix Update package name to 'vite-import-maps' and import { viteImportMaps } instead of { vitePluginNativeImportMaps }.

breaking Requires Vite >=6.0.0 (or Vite 7/8) as a peer dependency. Older Vite versions are not supported. ↓

fix Upgrade Vite to version 6.0.0 or later. For Vite 5 projects, stay on an older version or use a different plugin.

deprecated The 'outputAsFile' option may change in future versions. It is currently stable but not guaranteed to remain. ↓

fix Monitor changelog for updates; alternative: use 'injectImportMapsToHtml: false' and import the virtual module.

gotcha CommonJS module resolution uses static analysis via node/cjs-module-lexer; some CJS modules may not be detected correctly if they have side effects or dynamic exports. ↓

fix Ensure CJS modules have stable named exports. For problematic modules, use a custom entry with explicit export mapping.

gotcha When 'injectImportMapsToHtml' is false, you must manually import the virtual module 'virtual:importmap' and inject the script tag yourself. ↓

fix Add <script type="importmap">{{importMapContent}}</script> to your HTML template.

Install

npm install vite-import-maps

yarn add vite-import-maps

pnpm add vite-import-maps

Imports

viteImportMaps
wrong
```
import viteImportMaps from 'vite-import-maps'
```
correct
```
import { viteImportMaps } from 'vite-import-maps'
```
Named export, not default. Named export was renamed from 'vitePluginNativeImportMaps' in v0.2.0.
viteImportMaps (default)
wrong
```
import { viteImportMaps } from 'vite-import-maps'
```
correct
```
import viteImportMaps from 'vite-import-maps'
```
Since v0.2.0, a default export is also available; both work. However, the named export is recommended for explicit usage.

Types (PluginOptions)

wrong

import { PluginOptions } from 'vite-import-maps'

correct

import type { PluginOptions } from 'vite-import-maps'

Type-only import to avoid runtime inclusion.

CommonJS require
wrong
```
const viteImportMaps = require('vite-import-maps')
```
correct
```
const { viteImportMaps } = require('vite-import-maps')
```
CJS requires destructuring because the package exports both named and default. This works if your project uses CJS.
Old named export (deprecated)
wrong
```
import { vitePluginNativeImportMaps } from 'vite-plugin-native-import-maps'
```
correct
```
import { vitePluginNativeImportMaps } from 'vite-import-maps'
```
The plugin was renamed in v0.2.0. Old import path 'vite-plugin-native-import-maps' no longer exists; use 'vite-import-maps'.
Virtual module
wrong
```
import importMap from 'vite-import-maps/virtual:importmap'
```
correct
```
import importMap from 'virtual:importmap'
```
The virtual module is provided by the plugin; no file path needed. Use when injectImportMapsToHtml is false.

Quickstart

Sets up vite-import-maps to expose 'react' and 'react-dom' via browser import maps with SRI integrity and logging enabled.

// vite.config.ts
import { defineConfig } from 'vite';
import { viteImportMaps } from 'vite-import-maps';

export default defineConfig({
  plugins: [
    viteImportMaps({
      imports: ['react', 'react-dom'],
      integrity: 'sha384',
      log: true,
    }),
  ],
});