Registry / devops / rollup-plugin-unbundle

rollup-plugin-unbundle

library3.2.0jsnpmunverified

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.

devops web-framework

npm install rollup-plugin-unbundle

github ↗package ↗

INSTALL

IMPORT

SIG · ROLLUP-PLUGIN-UNBU

rollup-plugin-unbundle

devopsjavascriptv3.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

unbundle

✓ import unbundle from 'rollup-plugin-unbundle'

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

Default export only. ESM-only since v3.

unbundle

✓ import unbundle from 'rollup-plugin-unbundle'

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

Do not use namespace import; only default export.

UnbundleOptions

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

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

Type import, removed at runtime. Available since v3.

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 }), ], };

Debug

Known issues

breakingv3.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.

affects: >=3.0.0 <3.0.0

breakingv2.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.

affects: >=2.0.0 <2.0.0

deprecatedRollup 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.

affects: >=3.2.0

gotchaThe 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.

affects: >=1.0.0

gotchaWhen 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()].

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

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

Package not installed

fix

npm install rollup-plugin-unbundle

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

Trying to require() the ESM-only module

fix

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

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

Conflicting external configuration

fix

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

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

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.

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

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.

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

rolluprequiredpeer dependency - plugin requires Rollup to function

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/run-z/rollup-plugin-unbundle ↗

packagehttps://www.npmjs.com/package/rollup-plugin-unbundle ↗