vite-plugin-import-map

📦 Prefer the public version?
Use vite-plugin-module-alias — same functionality, no scope, ideal for production use.

A simple and flexible Vite plugin to inject an Import Map into your project. Supports both inline import maps and external import-map.json file. Automatically reloads the Vite dev server when the map is updated.

✨ Features

• Injects <script type="importmap"> into HTML automatically
• Supports inline imports or external import-map.json file
• Watches and triggers full reload on import map file changes
• Resolves import aliases in dev and marks them as external in production
• Optionally syncs TypeScript paths by updating tsconfig.json

💎 Value Proposition

Modern frontends often rely on import aliases for better DX and cleaner project structures. TypeScript supports this via tsconfig.json, but these aliases are only for type checking and editor autocomplete — they do not affect how modules are actually resolved in the browser or by Vite during development and production.

This plugin closes that gap by:

• Injecting a real <script type="importmap"> into your app's HTML
• Letting browsers resolve imports using native import maps
• Updating Vite’s resolve.alias so your dev environment aligns with your runtime
• Watching external import-map.json for changes and reloading automatically
• Optionally syncs aliases to your tsconfig.json file via the tsconfigPath option
• Automatically removes outdated aliases from paths to keep things clean
• Keeps TypeScript, IDE, Vite, and browser resolution fully aligned

Together, this ensures:

• Consistent resolution between editor, Vite, and browser
• Cleaner imports without relying on relative paths
• Improved maintainability and shared import maps across tooling

🧠 TypeScript integration

To keep type resolution working in your IDE, continue to define aliases in your tsconfig.json like so:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

Then let the plugin handle runtime resolution seamlessly.

📦 Installation

npm install @titovdima/vite-plugin-import-map --save-dev

or

yarn add @titovdima/vite-plugin-import-map --dev

🔧 Project Setup

This project uses ECMAScript Modules (ESM). To ensure it works correctly, make sure the following flag is set in your package.json:

{
  "type": "module"
}

🚀 Usage

You can configure the plugin in one of two ways — either by providing an inline imports object directly in your vite.config.ts, or by specifying a path to an external import-map.json file. Do not use both at once.

Option 1: Inline Import Map (via vite.config.ts)

import { defineConfig } from "vite";
import importMapPlugin from "@titovdima/vite-plugin-import-map";

export default defineConfig({
  plugins: [
    importMapPlugin({
      imports: {
        "@components": "/src/components",
        "@utils": "/src/utils",
      },
    }),
  ],
});

Option 2: External JSON File

You can define the import map in a separate import-map.json file at the project root:

{
  "imports": {
    "@components": "/src/components",
    "@utils": "/src/utils",
    "@assets": "/src/assets"
  }
}

🔤 Supported Format for Imports

The keys in the import map support the following formats:

• Exact match: "@components": "src/components" or "@components": "./src/components" or "@components": "/src/components"
• Note: All of the above will be normalized and resolved based on the project root.
• Important: Prefix matches (e.g. "@components/") are not currently supported.

Then use the plugin like this:

import { defineConfig } from "vite";
import importMapPlugin from "@titovdima/vite-plugin-import-map";

export default defineConfig({
  plugins: [
    importMapPlugin({
      importMapPath: "import-map.json",
    }),
  ],
});

📁 Example Imports

Now you can import modules using cleaner aliases:

import Button from "@components/Button";
import { formatDate } from "@utils/date";
import logo from "@assets/logo.png";

⚙️ Plugin Options

| Option | Type | Description | | --------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | imports | Record<string, string> | (optional) Inline import map. Only absolute paths starting with '/' are supported. Use either imports or importMapPath—both at once will cause an error. | | importMapPath | string | (optional) Path to external import-map.json file. Use either imports or importMapPath—both at once will cause an error. | | tsconfigPath | string | (optional) Path to tsconfig.json or a variant (e.g. tsconfig.app.json) to auto-sync TypeScript paths. | | autoRestart | boolean | (optional) Automatically restarts Vite server when importMapPath changes. Default is false. |

✅ Comments in tsconfig.json are now preserved when the plugin syncs paths — no more stripped-out comments, thanks to the switch to comment-json!

You must choose either imports or importMapPath — using both at the same time is not supported and will throw an error. This design ensures that the import map comes from only one source, preventing ambiguity.

🔧 TypeScript Path Syncing

When you specify the tsconfigPath option, the plugin will automatically update your TypeScript configuration to match your import map. This keeps editor IntelliSense and compile-time path resolution in sync with your runtime aliases.

• Aliases will be written to the compilerOptions.paths section.
• Any aliases removed from the import map will also be cleaned up in the tsconfig file.
• The plugin ensures paths use the @alias/* → path/to/* format required by TypeScript.

If `baseUrl` is not set, the plugin will default it to `"."` to ensure paths work as expected.

This is because TypeScript requires a baseUrl to correctly resolve paths, and "." ensures that all aliases are resolved relative to the project root.

ℹ️ After aliases are updated, you may need to restart the TypeScript server in your IDE for changes to take effect. Restarting the server ensures that all changes are applied.

Example: tsconfig.app.json

If you are using a project references setup, you may want to sync aliases into tsconfig.app.json instead of the root tsconfig.json.

importMapPlugin({
  importMapPath: "import-map.json",
  tsconfigPath: "tsconfig.app.json",
});

And the plugin will produce:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

This is necessary because the TypeScript Language Service in your IDE (e.g. VSCode) does not automatically reload the tsconfig.json file when it is modified. To apply the changes, you must restart the TypeScript server:

• In VSCode, use Ctrl+Shift+P → TypeScript: Restart TS Server.
• Alternatively, restart the Vite development server to reflect changes during runtime.

Server Restart Behavior

If you modify the import-map.json file while the dev server is running, you may need to restart Vite for changes to take full effect.

You have two options:

• Manual restart: The plugin will print a warning to remind you to restart the server.
• Automatic restart: Set autoRestart: true in the plugin config to have Vite restart automatically.

Note: Automatic restart uses Vite’s internal server.restart() API, which may change in future Vite versions. Use with care.

importMapPlugin({
  importMapPath: "import-map.json",
  tsconfigPath: "tsconfig.app.json",
  autoRestart: true, // 🚀 auto-restarts Vite when import map changes
});

📌 Notes

• The plugin injects the import map only in development.
• In production, paths are marked as external in the bundle, ensuring that imports are resolved correctly during runtime.

🛣 Roadmap

Planned features:

• [x] Plugin option to auto-sync with tsconfig paths
• [x] Automatic cleanup of removed aliases from tsconfig
• [ ] Support for dynamic import maps in production
• [ ] Better diagnostics for conflicting aliases

🙌 Contributors

Thanks to these awesome people for their contributions:

• @itisArshdeep – added support for preserving comments in tsconfig.json using comment-json

🧩 Dependencies

This plugin uses comment-json to safely read and write tsconfig.json files while preserving comments.

📄 License

This project is licensed under the MIT License.