> ## Documentation Index
> Fetch the complete documentation index at: https://sferadev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# rollup-plugin-import-cdn

> Import ESM modules from CDN URLs with tree-shaking support

A Rollup plugin that enables importing ESM modules from CDN URLs for local processing, allowing tree-shaking on non-local resources.

## Features

* **CDN Imports** - Import npm packages directly from CDN URLs
* **Tree-shaking** - Full tree-shaking support for CDN modules
* **Multiple CDNs** - Support for Skypack with fallback chains
* **Version Pinning** - Pin specific package versions
* **Custom Resolvers** - Use any CDN with custom URL resolvers

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install rollup-plugin-import-cdn
  ```

  ```bash pnpm theme={null}
  pnpm add rollup-plugin-import-cdn
  ```

  ```bash yarn theme={null}
  yarn add rollup-plugin-import-cdn
  ```
</CodeGroup>

## Quick Start

```javascript theme={null}
import { importCdn } from "rollup-plugin-import-cdn";

export default {
  input: "src/index.js",
  output: { file: "dist/bundle.js", format: "esm" },
  plugins: [importCdn()],
};
```

Now you can import packages directly from URLs:

```javascript theme={null}
// Resolved via Skypack by default
import { debounce } from "lodash-es";

// Direct URL import
import confetti from "https://esm.sh/canvas-confetti";
```

## Configuration

### Version Pinning

Pin specific versions for reproducible builds:

```javascript theme={null}
importCdn({
  versions: {
    react: "18.2.0",
    "react-dom": "18.2.0",
    lodash: "4.17.21",
  },
});
```

### Custom CDN Resolvers

Use any CDN by providing custom resolver functions:

```javascript theme={null}
importCdn({
  priority: [
    // Try esm.sh first
    (packageName) => `https://esm.sh/${packageName}`,
    // Fall back to Skypack
    "skypack",
    // Then try unpkg
    (packageName) => `https://unpkg.com/${packageName}?module`,
  ],
});
```

### Custom Fetch Implementation

For environments without global fetch or for adding custom headers:

```javascript theme={null}
import nodeFetch from "node-fetch";

importCdn({
  fetchImpl: nodeFetch,
});
```

## How It Works

1. **Resolution**: When Rollup encounters an import, the plugin checks if it's a CDN-resolvable module
2. **Fetching**: The module is fetched from the configured CDN(s)
3. **Transformation**: Relative imports within the fetched module are resolved to absolute CDN URLs
4. **Bundling**: Rollup processes the module like any local file, enabling tree-shaking

### Import Resolution

| Import Type    | Example                          | Behavior                    |
| -------------- | -------------------------------- | --------------------------- |
| Package name   | `import "lodash"`                | Resolved via CDN            |
| Scoped package | `import "@tanstack/react-query"` | Resolved via CDN            |
| Direct URL     | `import "https://esm.sh/react"`  | Fetched directly            |
| Local relative | `import "./local"`               | Ignored (handled by Rollup) |

## Popular CDN Examples

```javascript theme={null}
// esm.sh - Fast, global CDN
(pkg) => `https://esm.sh/${pkg}`

// unpkg - npm CDN
(pkg) => `https://unpkg.com/${pkg}?module`

// jsDelivr - Multi-CDN
(pkg) => `https://cdn.jsdelivr.net/npm/${pkg}/+esm`
```

## API Reference

### `importCdn(options?)`

Creates the Rollup plugin.

#### Options

| Option      | Type                                              | Default            | Description                            |
| ----------- | ------------------------------------------------- | ------------------ | -------------------------------------- |
| `fetchImpl` | `FetchImpl`                                       | `globalThis.fetch` | Fetch implementation for HTTP requests |
| `priority`  | `Array<AvailableCDNs \| (key: string) => string>` | `["skypack"]`      | CDN resolution priority                |
| `versions`  | `Record<string, string>`                          | `{}`               | Package version pinning                |

## Examples

### Vite Configuration

```javascript theme={null}
// vite.config.js
import { defineConfig } from "vite";
import { importCdn } from "rollup-plugin-import-cdn";

export default defineConfig({
  build: {
    rollupOptions: {
      plugins: [
        importCdn({
          versions: { three: "0.160.0" },
        }),
      ],
    },
  },
});
```

### Multi-CDN Fallback

```javascript theme={null}
importCdn({
  priority: [
    (pkg) => `https://esm.sh/${pkg}`,
    "skypack",
    (pkg) => `https://unpkg.com/${pkg}?module`,
  ],
});
```

## Types

```typescript theme={null}
import type {
  PluginOptions,
  FetchImpl,
  AvailableCDNs,
  Dependency,
} from "rollup-plugin-import-cdn";
```

## Compatibility

* **Rollup**: 3.x, 4.x
* **Node.js**: 18+ (requires `fetch` or custom `fetchImpl`)