{"id":22271,"library":"rollup-plugin-unbundle","title":"rollup-plugin-unbundle","description":"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.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/run-z/rollup-plugin-unbundle","tags":["javascript","rollup-plugin","bundle","typescript"],"install":[{"cmd":"npm install rollup-plugin-unbundle","lang":"bash","label":"npm"},{"cmd":"yarn add rollup-plugin-unbundle","lang":"bash","label":"yarn"},{"cmd":"pnpm add rollup-plugin-unbundle","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency - plugin requires Rollup to function","package":"rollup","optional":false}],"imports":[{"note":"Default export only. ESM-only since v3.","wrong":"const { unbundle } = require('rollup-plugin-unbundle')","symbol":"unbundle","correct":"import unbundle from 'rollup-plugin-unbundle'"},{"note":"Do not use namespace import; only default export.","wrong":"import * as unbundle from 'rollup-plugin-unbundle'","symbol":"unbundle","correct":"import unbundle from 'rollup-plugin-unbundle'"},{"note":"Type import, removed at runtime. Available since v3.","wrong":"import { UnbundleOptions } from 'rollup-plugin-unbundle'","symbol":"UnbundleOptions","correct":"import type { UnbundleOptions } from 'rollup-plugin-unbundle'"}],"quickstart":{"code":"import unbundle from 'rollup-plugin-unbundle';\n\nexport default {\n  input: 'src/index.js',\n  output: {\n    format: 'esm',\n    file: 'dist/bundle.js',\n  },\n  plugins: [\n    unbundle({\n      // Externalize all dependencies and peerDependencies\n      // Node built-ins are externalized automatically\n    }),\n  ],\n};","lang":"typescript","description":"Show minimal rollup.config.js that uses the plugin to externalize dependencies and Node.js built-ins."},"warnings":[{"fix":"Update to v3.x and ensure no reliance on previous external patching behavior.","message":"v3.0.0 changed the plugin to use resolveId hook instead of patching external option. This may affect custom resolution behavior.","severity":"breaking","affected_versions":">=3.0.0 <3.0.0"},{"fix":"Review resolution behavior when upgrading from v1.x.","message":"v2.0.0 switched to Node.js package kit for import resolution, changing how packages are resolved.","severity":"breaking","affected_versions":">=2.0.0 <2.0.0"},{"fix":"Upgrade to Rollup v4 if needed, or stay on v3.x.","message":"Rollup v3 and earlier support dropped in v3.2.0+, but v3.2.0 still supports Rollup 2.79.1 - 5.0.","severity":"deprecated","affected_versions":">=3.2.0"},{"fix":"Set sideEffects: false in your package.json to enable tree-shaking, or define sideEffects explicitly.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Order plugins: [nodeResolve(), unbundle()].","message":"When used with @rollup/plugin-node-resolve, the plugin must be placed after node-resolve in the plugins array to work correctly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use the external option in Rollup or configure monorepo packages manually.","message":"The plugin does not handle monorepo dependencies automatically; you may need to add custom external patterns.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"npm install rollup-plugin-unbundle","cause":"Package not installed","error":"Error: Cannot find module 'rollup-plugin-unbundle'"},{"fix":"Use import unbundle from 'rollup-plugin-unbundle' instead of require()","cause":"Trying to require() the ESM-only module","error":"TypeError: (0 , rollup_plugin_unbundle_1.default) is not a function"},{"fix":"Remove global 'external' option if using unbundle plugin, or use custom external function.","cause":"Conflicting external configuration","error":"The plugin 'unbundle' uses the 'resolveId' hook, which is not compatible with Rollup's 'external' option when used without 'custom'..."},{"fix":"Ensure your package.json has a sideEffects field; set to false if side-effect-free.","cause":"Unbundle plugin may not detect side effects correctly if package.json lacks sideEffects field","error":"Error: Unexpected module side effects... (or tree-shaking not working)"},{"fix":"Check that the package is installed. If using @rollup/plugin-node-resolve, ensure it's placed before unbundle.","cause":"Package is not in node_modules or not resolved correctly","error":"Module not found: Error: Can't resolve 'somePackage'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}