esbuild-plugin-cdn-imports

2.0.0 verified Fri May 01 auth: no javascript

An esbuild plugin (v2.0.0) that intercepts import statements and resolves them to CDN URLs (esm.sh, unpkg, jsdelivr, skypack), enabling browser-side module resolution without a filesystem. Requires esbuild >=0.20.0 and Node >=18. Ships TypeScript types. Key differentiator: supports multiple CDNs and per-package version pinning, but some dependencies may not work from a CDN.

Common errors

error Error: Cannot find module 'esbuild-plugin-cdn-imports' ↓

cause Package not installed correctly or missing peer dependency.

fix

Run 'npm install -D esbuild esbuild-plugin-cdn-imports'.

error TypeError: CDNImports is not a function ↓

cause Import might be using default import instead of named import.

fix

Use 'import { CDNImports } from 'esbuild-plugin-cdn-imports''.

error Error: [plugin: cdn-imports] Unsupported CDN 'xyz' ↓

cause Provided CDN name is not in the supported list.

fix

Use one of: 'esm', 'unpkg', 'jsdelivr', 'skypack'.

error Build failed with 1 error: error: require() of ES Module not supported ↓

cause The project is using CommonJS require() to import an ESM-only plugin.

fix

Switch to ES module imports or set 'type': 'module' in package.json.

Warnings

breaking Node.js >=18 required; plugin uses modern APIs (e.g., node:module) not available in older versions. ↓

fix Upgrade Node.js to version 18 or later.

breaking esbuild >=0.20.0 required as peer dependency. ↓

fix Update esbuild to version 0.20.0 or later.

deprecated Support for esbuild <0.19.0 dropped in v1.2.0; earlier versions may use an older plugin version. ↓

fix Upgrade esbuild to at least 0.19.0.

gotcha Some npm packages (e.g., those with native modules or certain Node.js APIs) may not work when imported from a CDN. ↓

fix Use the 'exclude' option to bypass CDN resolution for incompatible packages, or verify CDN compatibility beforehand.

breaking ESM-only package; cannot be imported with CommonJS require(). ↓

fix Use import syntax instead of require(), or set your project's type to module.

deprecated The 'skypack' CDN may be less reliable; esm.sh and jsdelivr are recommended. ↓

fix Prefer 'esm' or 'jsdelivr' CDN options.

Install

npm install esbuild-plugin-cdn-imports

yarn add esbuild-plugin-cdn-imports

pnpm add esbuild-plugin-cdn-imports

Imports

CDNImports

wrong

import CDNImports from 'esbuild-plugin-cdn-imports'

correct

import { CDNImports } from 'esbuild-plugin-cdn-imports'

Named export only; no default export.

CDNImports

wrong

const { CDNImports } = require('esbuild-plugin-cdn-imports')

correct

import { CDNImports } from 'esbuild-plugin-cdn-imports'

ESM-only package; CJS require not supported.

CDNImportsOptions
```
import type { CDNImportsOptions } from 'esbuild-plugin-cdn-imports'
```
TypeScript users should import the type for options validation.

Quickstart

Configures esbuild to replace imports of 'react' and 'react-dom' with esm.sh CDN URLs, excluding '@prisma/client' from transformation.

import { build } from 'esbuild';
import { CDNImports } from 'esbuild-plugin-cdn-imports';

await build({
  entryPoints: ['./src/index.js'],
  bundle: true,
  outfile: './dist/bundle.js',
  format: 'esm',
  platform: 'browser',
  plugins: [
    CDNImports({
      cdn: 'esm',
      versions: {
        'react': '17.0.2',
        'react-dom': '17.0.2'
      },
      exclude: ['@prisma/client']
    })
  ]
});