Vite Plugin Resolve Externals

0.2.2 verified Mon Apr 27 auth: no javascript

A Vite plugin (v0.2.2) that resolves external dependencies by mapping import specifiers to global variables or custom code snippets. It allows configuring external mappings via plugin options or Vite's resolve.externals configuration. Useful for replacing Node.js or client-side libraries with CDN scripts in Vite projects. It supports both simple global mappings and advanced code generation for scoped exports. No recent updates; stable but minimal feature set compared to alternatives like rollup-plugin-external-globals. Suitable for small to medium projects needing quick externals resolution.

Common errors

error Error: Cannot find module 'vite-plugin-resolve-externals' ↓

cause Package not installed or used in TypeScript without type declarations.

fix

Install as devDependency: npm install -D vite-plugin-resolve-externals

error TypeError: resolveExternalsPlugin is not a function ↓

cause Using named import instead of default import.

fix

Use 'import resolveExternalsPlugin from ...' or 'import * as pkg from ...; pkg.default(...)'

error SyntaxError: Unexpected token 'export' ↓

cause Using require() in an ESM context (vite.config.js is ESM by default).

fix

Replace require() with import or use dynamic import: const resolve = (await import(...)).default

error Error: The externals option in 'resolve' is not supported by this plugin anymore ↓

cause Plugin version prior to 0.2.0? Actually, version 0.2.0+ ignores resolve.externals.

fix

Pass externals directly to resolveExternalsPlugin() as the first argument.

Warnings

gotcha The plugin overrides Vite's resolve.externals if both are set. Configure via plugin option only to avoid conflicts. ↓

fix Prefer passing externals as the first argument to resolveExternalsPlugin() instead of using resolve.externals in Vite config.

gotcha When using custom code strings for globals, ensure they are valid JavaScript. Syntax errors will cause silent build failures. ↓

fix Wrap custom exports in a function that returns a template literal. Test by building with --debug flag.

deprecated The 'resolve.externals' configuration in Vite's resolve option is deprecated; use the plugin's argument instead. ↓

fix Move externals from resolve.externals to the plugin call: resolveExternalsPlugin({...})

breaking Plugin no longer reads from 'resolve.externals' by default; must pass explicitly. ↓

fix Pass externals as argument to resolveExternalsPlugin().

gotcha Named exports from custom code strings may not work if the global variable is not defined at build time. ↓

fix Ensure the global is available in the browser before the script runs, e.g., via CDN script tags.

Install

npm install vite-plugin-resolve-externals

yarn add vite-plugin-resolve-externals

pnpm add vite-plugin-resolve-externals

Imports

default

wrong

const resolveExternalsPlugin = require('vite-plugin-resolve-externals')

correct

import resolveExternalsPlugin from 'vite-plugin-resolve-externals'

The package is ESM-only. Use import syntax for Vite config.

resolveExternalsPlugin (default)

wrong

import { resolveExternalsPlugin } from 'vite-plugin-resolve-externals'

correct

import * as plugin from 'vite-plugin-resolve-externals'

The package exports a single default function; no named export exists.

resolveExternalsPlugin via CJS require()

wrong

const resolveExternalsPlugin = require('vite-plugin-resolve-externals')

correct

const resolveExternalsPlugin = (await import('vite-plugin-resolve-externals')).default

CommonJS require() will fail in ESM context. Use dynamic import() with .default.

Quickstart

Basic setup: map 'vue' to global 'Vue', 'vue-router' to 'VueRouter', 'axios' to 'axios' in Vite project.

// vite.config.js
import { defineConfig } from 'vite';
import resolveExternalsPlugin from 'vite-plugin-resolve-externals';

export default defineConfig({
  plugins: [
    resolveExternalsPlugin({
      vue: 'Vue',
      'vue-router': 'VueRouter',
      axios: 'axios',
    }),
  ],
});