vite-plugin-cdn-import

1.0.1 verified Mon Apr 27 auth: no javascript

Vite plugin that externalizes specified npm packages and loads them from a CDN (jsDelivr, unpkg, cdnjs) in production builds. v1.0.1 supports Vite 2–5, TypeScript types, custom script/link tag generation, presets for react, vue, lodash, etc., and development mode. Unlike generic external plugins (e.g., vite-plugin-externals), it automatically injects CDN script/link tags and offers built-in presets for common libraries. Releases are infrequent; v1.0.0 introduced breaking changes to the options API.

Common errors

error Error: The package 'vite-plugin-cdn-import' is not ESM (CommonJS) and cannot be imported via require() ↓

cause Using CommonJS require() instead of ESM import in vite.config.ts.

fix

Use 'import cdn from 'vite-plugin-cdn-import'' and ensure vite.config.ts is treated as ESM (set type: module in package.json or rename .mjs).

error [vite] Cannot find module 'vite-plugin-cdn-import' ↓

cause Package is not installed or not added to package.json.

fix

Run 'npm install vite-plugin-cdn-import --save-dev' and verify it appears in devDependencies.

error Uncaught ReferenceError: React is not defined ↓

cause The CDN script is not injected because the module is not in the modules list, or 'var' does not match the global variable.

fix

Ensure the package name and 'var' (e.g., 'React') are correct and the module is included in options.modules.

error TypeError: Cannot read properties of undefined (reading 'map') ↓

cause options.modules is undefined or not an array.

fix

Pass a 'modules' array to the plugin, e.g., cdn({ modules: ['react'] }).

Warnings

deprecated autoComplete option is deprecated since v1.0.1. Pass required packages directly in options.modules instead. ↓

fix Remove autoComplete; add the package name (e.g., 'react') directly to the modules array.

breaking In v1.0.0, the plugin updated to Vite 5, dropping support for older Vite versions. Some presets were removed from autoComplete. ↓

fix If using Vite 4 or earlier, stick with v0.x. Update modules manually for any removed presets.

gotcha Plugin does NOT work in development mode by default. Set 'enableInDevMode: true' to load from CDN during dev. ↓

fix Add 'enableInDevMode: true' to your plugin options if you need CDN scripts in dev.

gotcha Presets (e.g., 'react') only work for known packages. For custom packages you must provide full Module object with 'var' and 'path'. ↓

fix Define a Module object with name, var, path (and optional css) for any package not in the preset list.

gotcha The 'prodUrl' default uses jsDelivr. To switch to unpkg, cdnjs, or others, you must set 'prodUrl' or override per module. ↓

fix Set the 'prodUrl' option to your desired CDN URL template (e.g., 'https://unpkg.com/{name}@{version}/{path}').

Install

npm install vite-plugin-cdn-import

yarn add vite-plugin-cdn-import

pnpm add vite-plugin-cdn-import

Imports

default

wrong

const cdn = require('vite-plugin-cdn-import')

correct

import cdn from 'vite-plugin-cdn-import'

ESM-only; no CommonJS export. Must be used with Vite's ESM config.

Plugin type (optional)
```
import type { Options } from 'vite-plugin-cdn-import'
```
Type import for configuration options; use with TypeScript projects.

Preset modules

wrong

cdn({ modules: [{ name: 'react' }] }) without 'var' and 'path'

correct

cdn({ modules: ['react', 'react-dom'] })

Preset modules only require 'name' string; custom modules need full spec.

Quickstart

Configures Vite to externalize react and react-dom to CDN, showing custom module definition and prodUrl override.

// npm install vite-plugin-cdn-import --save-dev
// vite.config.ts
import { defineConfig } from 'vite';
import cdn from 'vite-plugin-cdn-import';

export default defineConfig({
  plugins: [
    cdn({
      modules: [
        {
          name: 'react',
          var: 'React',
          path: 'umd/react.production.min.js',
        },
        {
          name: 'react-dom',
          var: 'ReactDOM',
          path: 'umd/react-dom.production.min.js',
        },
      ],
      // optional development mode (default false)
      enableInDevMode: false,
      // optional custom CDN url template
      prodUrl: 'https://unpkg.com/{name}@{version}/{path}',
    }),
  ],
});