rollup-plugin-external-assets

4.1.1 verified Mon Apr 27 auth: no javascript

A Rollup plugin that externalizes assets (e.g., images, fonts) so they are not bundled into the JavaScript output, but are still copied to the output directory with hashed filenames. Current stable version is 4.1.1, released April 2024. The plugin uses Rollup's asset emission system to handle deduplication and hashing. Key differentiators: it avoids bundling assets inline, preserving import paths as require() or dynamic imports pointing to the emitted asset files. It supports include/exclude patterns, custom resolve base directory, and works with static and dynamic imports. TypeScript types are included. Notable breaking changes in v4: switched to named export only (no default export) and changed the function signature.

Common errors

error Error: The plugin `rollup-plugin-external-assets` has no default export. ↓

cause Trying to import the default export after upgrading to v4 (named export only).

fix

Use named import: import { externalAssets } from 'rollup-plugin-external-assets'.

error TypeError: externalAssets is not a function ↓

cause Loaded a different version or wrong import style; e.g., using `const externalAssets = require(...)` without destructuring.

fix

Use const { externalAssets } = require('rollup-plugin-external-assets').

error ENOENT: no such file or directory, open 'path/to/non-normalized\windows\path.png' ↓

cause Non-normalized Windows paths in patterns or resolve option (issue fixed in v3.0.0).

fix

Use forward slashes in all patterns and resolve paths, or upgrade to v3.0.0+.

Warnings

breaking v4 removed the default export. Import must use named export. ↓

fix Use `import { externalAssets } from 'rollup-plugin-external-assets'` instead of default import.

breaking v4 changed the function signature. Options are now passed as a single argument (pattern or options object) instead of (include, exclude, options). ↓

fix Update plugin call: `externalAssets('assets/*')` or `externalAssets({ include: 'assets/*' })`.

deprecated v2 deprecated the old `options` parameter; use the new signature. ↓

fix Switch to the new function signature.

gotcha Windows paths can cause issues with pattern matching; ensure patterns use forward slashes. ↓

fix Use forward slashes in include/exclude patterns (e.g., 'assets/**/*.png').

gotcha Empty source map files may be emitted (issue #75) – fixed in 4.1.1. ↓

fix Upgrade to version 4.1.1 or later.

Install

npm install rollup-plugin-external-assets

yarn add rollup-plugin-external-assets

pnpm add rollup-plugin-external-assets

Imports

externalAssets

wrong

import externalAssets from 'rollup-plugin-external-assets'

correct

import { externalAssets } from 'rollup-plugin-external-assets'

v4 removed the default export; only named export 'externalAssets' is available.

externalAssets

wrong

const externalAssets = require('rollup-plugin-external-assets')

correct

const { externalAssets } = require('rollup-plugin-external-assets')

CommonJS users must destructure the named export.

type ExternalAssetsOptions
```
import type { ExternalAssetsOptions } from 'rollup-plugin-external-assets'
```
TypeScript users can import the options type for type safety.

Quickstart

Configures Rollup to externalize PNG and JPG files, copying them to the output directory with hashed names.

// rollup.config.js
import { externalAssets } from 'rollup-plugin-external-assets';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'cjs'
  },
  plugins: [
    externalAssets([
      '**/*.png',
      '**/*.jpg'
    ])
  ]
};

// src/index.js
import logo from './assets/logo.png';
console.log(logo); // './assets/logo-abc123.png'