vite-plugin-importmap

0.1.1 verified Mon Apr 27 auth: no javascript

Vite plugin (v0.1.1) that enables import map-like path resolution by environment variable (mark). Allows conditional module replacement per build target using string suffix conventions, arrays, or JSON config files. Unlike standard Vite resolve aliases, it switches between file variants based on a single mark. Minimal API surface, ESM-only, ships TypeScript definitions. Release cadence is low; single maintainer. Suitable for multi-tenant or configurable builds.

Common errors

error TypeError: importmap is not a function ↓

cause Using CommonJS require() instead of ESM import.

fix

Change to import importmap from 'vite-plugin-importmap' and ensure vite.config.js uses ESM or type: module in package.json.

error [vite] The plugin 'vite-plugin-importmap' didn't output a plugin object. ↓

cause Calling importmap() without parentheses or passing invalid argument.

fix

Call importmap(mark) with a string argument; e.g., importmap('v1').

error Module not found: Can't resolve 'test.v1.js' ↓

cause mark is set but no matching file variant exists (e.g., test.v1.js not found).

fix

Ensure the variant file exists with the correct naming pattern (e.g., test.v1.js) or adjust the mark value.

Warnings

gotcha mark must be set at build time; missing env variable reverts to original import path without transformation. ↓

fix Set VITE_OPEN_TYPE environment variable or pass a string directly to importmap().

gotcha Plugin does not support dynamic imports or import() expressions; only static import/require statements are transformed. ↓

fix Use static imports; avoid dynamic import() for variant switching.

gotcha File resolution relies on exact suffixes; mismatched naming conventions (e.g., case sensitivity) will not be resolved. ↓

fix Ensure file variants match the pattern: baseName.<variant>.ext for string mode, or baseName[v1,v2].ext for array mode.

Install

npm install vite-plugin-importmap

yarn add vite-plugin-importmap

pnpm add vite-plugin-importmap

Imports

importmap

wrong

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

correct

import importmap from 'vite-plugin-importmap'

Default export; ESM-only. CJS require() will fail.

Quickstart

Configures vite-plugin-importmap with an environment-based 'mark' to switch resolved file variants.

// vite.config.js
import { defineConfig } from 'vite';
import importmap from 'vite-plugin-importmap';

const mark = process.env.VITE_OPEN_TYPE ?? 'v1';

export default defineConfig({
  plugins: [importmap(mark)]
});