Unbundle (Some) Dependencies

Rollup plugin helping to decide what modules to externalize, and what to bundle. It's not always easy, especially when plugins like @rollup/plugin-node-resolve replace module names with file paths.

By default, the plugin does the following:

• Resolves packages.

• Externalizes Node.js built-ins.

• Externalizes packages listed as package dependencies.

  As they will be installed along the bundled package anyway.

• Externalizes packages listed as package peerDependencies.

  As they expected to be added to the package that depends on bundled one.

• Maps module IDs back to their package names if necessary.

• Detects side effects of modules according to sideEffects property in their package.json files.

• Respects external option and other plug-ins resolutions.

Example Configuration

Add the following rollup.config.js:

import unbundle from 'rollup-plugin-unbundle';

export default {
  input: './src/index.js',
  plugins: [
    unbundle({
      /* Unbundle options */
    }),
  ],
  output: {
    format: 'esm',
    sourcemap: true,
    file: 'dist/index.js',
  },
};
Copy

Options

The plugin utilizes import resolution API to make decisions. Some of its behavior can be customized with appropriate options.

See Node.js package kit documentation for the details.

resolutionRoot

Resolution root of the imports.

One of:

• path to the root package directory,
• an ImportResolution instance (may cause issues with watch mode), or
• a function returning ImportResolution instance or a promise-like instance resolving to one.

By default, new resolution root will be created for the package in current working directory.

isExternal

This method decides whether to bundle the module or not. May be asynchronous.

Unlike external Rollup option, this method can be asynchronous. It accepts UnbundleRequest class instance that helps in making decisions.

UnbundleRequest has the following API:

• resolutionRoot - Imports resolution root.

• moduleId - The identifier of the module in question.

• isResolved - Whether the module has been resolved by e.g. plugins.

• importerId - The identifier of the module doing the import, if known.

• resolveImporter() - Asynchronously resolves the module doing the import.

  Either the importer module, or resolution root when the former is missing.

• resolveModule() - Asynchronously resolves the module in question.

• isExternal() - Asynchronously checks whether the module should be bundled or not according to default plugin logic.

  This can be used to retain the default plugin functionality for some modules.

Package Resolution

This plugin resolves packages using standard Node.js module resolution machinery. This means the imported modules might be in CommonJS format. E.g. when the importer package doesn't have a "type": "module" in its package.json, or when the imported package is in CommonJS format. This is not a problem if the imported package is externalized. Otherwise, a CommonJS support has to be enabled, e.g. with @rollup/plugin-commonjs plug-in:

import commonjs from '@rollup/plugin-commonjs';
import unbundle from 'rollup-plugin-unbundle';

export default {
  input: './src/index.js',
  plugins: [unbundle(), commonjs()],
  output: {
    format: 'esm',
    sourcemap: true,
    file: 'dist/index.js',
  },
};
Copy

Alternatively, a @rollup/plugin-node-resolve plug-in can be used with config like this:

import nodeResolve from '@rollup/plugin-node-resolve';
import unbundle from 'rollup-plugin-unbundle';

export default {
  input: './src/index.js',
  plugins: [unbundle(), nodeResolve()],
  output: {
    format: 'esm',
    sourcemap: true,
    file: 'dist/index.js',
  },
};
Copy

Place node-resolve plug-in after unbundle one to prefer node-resolve resolutions.

Even with node-resolve enabled, the unbundle plug-in maps resolved files back to their package names and thus decides whether to externalize them.