rollup-plugin-unbundle

3.2.0 verified Mon Apr 27 auth: no javascript

Rollup plugin to externalize dependencies that should not be bundled (e.g., dependencies, peerDependencies, Node.js built-ins). v3.2.0 adds Rollup v4 support. Maintained actively, with a focus on correct externalization and side-effect detection. Unlike manual external configuration, it integrates with @rollup/plugin-node-resolve and respects the package.json sideEffects field. Requires Node >=16.15 and Rollup 2.79.1 - 5.0. Ships TypeScript definitions.

Common errors

error Error: Cannot find module 'rollup-plugin-unbundle' ↓

cause Package not installed

fix

npm install rollup-plugin-unbundle

error TypeError: (0 , rollup_plugin_unbundle_1.default) is not a function ↓

cause Trying to require() the ESM-only module

fix

Use import unbundle from 'rollup-plugin-unbundle' instead of require()

error The plugin 'unbundle' uses the 'resolveId' hook, which is not compatible with Rollup's 'external' option when used without 'custom'... ↓

cause Conflicting external configuration

fix

Remove global 'external' option if using unbundle plugin, or use custom external function.

error Error: Unexpected module side effects... (or tree-shaking not working) ↓

cause Unbundle plugin may not detect side effects correctly if package.json lacks sideEffects field

fix

Ensure your package.json has a sideEffects field; set to false if side-effect-free.

error Module not found: Error: Can't resolve 'somePackage' ↓

cause Package is not in node_modules or not resolved correctly

fix

Check that the package is installed. If using @rollup/plugin-node-resolve, ensure it's placed before unbundle.

Warnings

breaking v3.0.0 changed the plugin to use resolveId hook instead of patching external option. This may affect custom resolution behavior. ↓

fix Update to v3.x and ensure no reliance on previous external patching behavior.

breaking v2.0.0 switched to Node.js package kit for import resolution, changing how packages are resolved. ↓

fix Review resolution behavior when upgrading from v1.x.

deprecated Rollup v3 and earlier support dropped in v3.2.0+, but v3.2.0 still supports Rollup 2.79.1 - 5.0. ↓

fix Upgrade to Rollup v4 if needed, or stay on v3.x.

gotcha The plugin uses the sideEffects field from package.json to determine module side effects; if absent, all modules are considered side-effect-free (tree-shakable). ↓

fix Set sideEffects: false in your package.json to enable tree-shaking, or define sideEffects explicitly.

gotcha When used with @rollup/plugin-node-resolve, the plugin must be placed after node-resolve in the plugins array to work correctly. ↓

fix Order plugins: [nodeResolve(), unbundle()].

gotcha The plugin does not handle monorepo dependencies automatically; you may need to add custom external patterns. ↓

fix Use the external option in Rollup or configure monorepo packages manually.

Install

npm install rollup-plugin-unbundle

yarn add rollup-plugin-unbundle

pnpm add rollup-plugin-unbundle

Imports

unbundle

wrong

const { unbundle } = require('rollup-plugin-unbundle')

correct

import unbundle from 'rollup-plugin-unbundle'

Default export only. ESM-only since v3.

unbundle

wrong

import * as unbundle from 'rollup-plugin-unbundle'

correct

import unbundle from 'rollup-plugin-unbundle'

Do not use namespace import; only default export.

UnbundleOptions

wrong

import { UnbundleOptions } from 'rollup-plugin-unbundle'

correct

import type { UnbundleOptions } from 'rollup-plugin-unbundle'

Type import, removed at runtime. Available since v3.

Quickstart

Show minimal rollup.config.js that uses the plugin to externalize dependencies and Node.js built-ins.

import unbundle from 'rollup-plugin-unbundle';

export default {
  input: 'src/index.js',
  output: {
    format: 'esm',
    file: 'dist/bundle.js',
  },
  plugins: [
    unbundle({
      // Externalize all dependencies and peerDependencies
      // Node built-ins are externalized automatically
    }),
  ],
};