vite-import-maps weekly downloads statistics

vite-import-maps

Generate browser import maps from the modules Vite resolves in development and emits in production.

vite-import-maps keeps a browser import map aligned with Vite's module resolution. Declare packages or local entry points once; the plugin resolves them through the dev server and emits dedicated chunks during a production build.

It is designed for micro-frontends, plugin systems, and applications that load ESM modules at runtime while hosting shared dependencies themselves.

• Works in Vite development and production builds • Maps package specifiers and local ESM wrapper modules • Injects the map into HTML, exposes it as a virtual module, or emits JSON • Optionally adds integrity metadata to production chunks • Runs integration tests against Vite 6, 7, and 8

Table of contents

• Install • Quick start • Do you need this plugin? • Configuration • Consume the import map • Remote builds • CommonJS compatibility • Browser compatibility • How it works • Troubleshooting • Examples • Development • License

Install

Requirements

• Vite 6 or newer • A Node.js version that provides util.styleText: • Node.js 20.12.0 or newer on the 20.x release line • Node.js 21.7.0 or newer on the 21.x release line • Node.js 22 or newer

Quick start

Add the plugin to the host application—the application that serves the import map and shared modules:

Package entries such as clsx and react must already be installed in the host project.

By default, the plugin prepends an import map to the generated HTML. A simplified production map looks like this:

Production filenames follow your Vite output configuration, so they may include hashes.

[!NOTE] React, clsx, and other npm packages may resolve to CommonJS entry points. The plugin provides a compatibility wrapper when it can detect their exports. For explicit control, expose a local ESM wrapper such as react-esm.ts. See CommonJS compatibility.

[!IMPORTANT] If a separately built remote imports one of these specifiers, configure that dependency as external in the remote build. Otherwise the remote will bundle its own copy and the import map will not provide a shared instance.

Do you need this plugin?

This plugin is a good fit when the browser loads ESM modules at runtime and more than one part of your application needs to resolve the same bare import specifiers.

Typical use cases include:

• Micro-frontends — A host and independently delivered remotes need to resolve shared dependencies such as React, Vue, or Solid. • Plugin systems — Runtime-loaded plugins import APIs or libraries provided by the host application. • Self-hosted dependency sharing — You want the host to build and serve shared modules instead of loading them from a public CDN. • Custom public entry points — You want an import-map specifier to resolve to a local wrapper, a curated set of exports, or an application-owned module.

The plugin is most valuable when you want to use browser import maps without manually keeping development URLs and production chunk filenames in sync. The host becomes the source of truth: it resolves each configured entry with Vite, then exposes the resulting map to the browser.

You may not need it when

• Your application does not load modules at runtime. • Every dependency can stay inside one conventional application bundle. • A CDN-generated import map already meets your deployment and versioning requirements. • You need a complete micro-frontend runtime with remote discovery, version negotiation, fallbacks, or deployment orchestration. This plugin generates and exposes import maps; it does not provide those higher-level features.

Why self-host shared modules?

Public services such as esm.sh and JSPM are convenient and may be the simplest option for some applications. Self-hosting is useful when you need tighter control over:

• Availability — Shared modules are deployed with infrastructure you operate. • Network policy — The application does not depend on access to a public module CDN. • Version alignment — The host build determines the exact dependency versions it exposes. • Customization — Local ESM wrappers can adapt exports or provide application-specific entry points.

Remote modules do not need a Vite plugin to consume the generated map. They can be plain browser ESM.

Configuration

| Option | Default | Description |

| imports | required | Package specifiers or { name, entry } mappings to expose. name is the public specifier; entry is the package or local file Vite resolves. | | modulesOutDir | "" | Directory prefix for emitted shared chunks, relative to Vite's build output. | | integrity | false | Adds an integrity metadata map in production. true uses sha384; a hash name selects the algorithm. | | log | false | Enables detailed dependency-resolution logging. | | injectImportMapsToHtml | true | Injects through Vite's transformIndexHtml hook. Disable it when another layer owns the HTML, including most SSR setups. | | importMapHtmlTransformer | identity | Transforms the complete resolved import-map object. It can rewrite URLs or add fields such as scopes. | | outputAsFile | false | true serves/emits import-map.json; a string changes the basename, for example "runtime-map" produces runtime-map.json. |

Package entries

A string uses the same value as the public specifier and the module Vite resolves:

Use the object form when the public specifier and resolved entry differ:

Local entries are useful for exposing a controlled subset of exports or wrapping a CommonJS dependency in ESM.

Integrity metadata

Set one default for every entry, then override individual dependencies when needed:

Integrity hashes are calculated from emitted production chunks. Development import maps do not include integrity metadata.

Transform the generated map

The transformer receives the full import map plus the registered entries and internal store:

The transformed result is shared by HTML injection, the virtual module, and JSON-file output.…

Description from the npm listing.