{"id":22017,"library":"rollup-plugin-external-assets","title":"rollup-plugin-external-assets","description":"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.","status":"active","version":"4.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/recursive-beast/rollup-plugin-external-assets","tags":["javascript","rollup-plugin","assets","import","external","typescript"],"install":[{"cmd":"npm install rollup-plugin-external-assets","lang":"bash","label":"npm"},{"cmd":"yarn add rollup-plugin-external-assets","lang":"bash","label":"yarn"},{"cmd":"pnpm add rollup-plugin-external-assets","lang":"bash","label":"pnpm"}],"dependencies":null,"imports":[{"note":"v4 removed the default export; only named export 'externalAssets' is available.","wrong":"import externalAssets from 'rollup-plugin-external-assets'","symbol":"externalAssets","correct":"import { externalAssets } from 'rollup-plugin-external-assets'"},{"note":"CommonJS users must destructure the named export.","wrong":"const externalAssets = require('rollup-plugin-external-assets')","symbol":"externalAssets","correct":"const { externalAssets } = require('rollup-plugin-external-assets')"},{"note":"TypeScript users can import the options type for type safety.","symbol":"type ExternalAssetsOptions","correct":"import type { ExternalAssetsOptions } from 'rollup-plugin-external-assets'"}],"quickstart":{"code":"// rollup.config.js\nimport { externalAssets } from 'rollup-plugin-external-assets';\n\nexport default {\n  input: 'src/index.js',\n  output: {\n    dir: 'dist',\n    format: 'cjs'\n  },\n  plugins: [\n    externalAssets([\n      '**/*.png',\n      '**/*.jpg'\n    ])\n  ]\n};\n\n// src/index.js\nimport logo from './assets/logo.png';\nconsole.log(logo); // './assets/logo-abc123.png'","lang":"javascript","description":"Configures Rollup to externalize PNG and JPG files, copying them to the output directory with hashed names."},"warnings":[{"fix":"Use `import { externalAssets } from 'rollup-plugin-external-assets'` instead of default import.","message":"v4 removed the default export. Import must use named export.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update plugin call: `externalAssets('assets/*')` or `externalAssets({ include: 'assets/*' })`.","message":"v4 changed the function signature. Options are now passed as a single argument (pattern or options object) instead of (include, exclude, options).","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Switch to the new function signature.","message":"v2 deprecated the old `options` parameter; use the new signature.","severity":"deprecated","affected_versions":">=2.0.0 <4.0.0"},{"fix":"Use forward slashes in include/exclude patterns (e.g., 'assets/**/*.png').","message":"Windows paths can cause issues with pattern matching; ensure patterns use forward slashes.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Upgrade to version 4.1.1 or later.","message":"Empty source map files may be emitted (issue #75) – fixed in 4.1.1.","severity":"gotcha","affected_versions":"<4.1.1"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use named import: `import { externalAssets } from 'rollup-plugin-external-assets'`.","cause":"Trying to import the default export after upgrading to v4 (named export only).","error":"Error: The plugin `rollup-plugin-external-assets` has no default export."},{"fix":"Use `const { externalAssets } = require('rollup-plugin-external-assets')`.","cause":"Loaded a different version or wrong import style; e.g., using `const externalAssets = require(...)` without destructuring.","error":"TypeError: externalAssets is not a function"},{"fix":"Use forward slashes in all patterns and resolve paths, or upgrade to v3.0.0+.","cause":"Non-normalized Windows paths in patterns or resolve option (issue fixed in v3.0.0).","error":"ENOENT: no such file or directory, open 'path/to/non-normalized\\windows\\path.png'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}