Rollup Plugin Node Resolve: Handling Node Resolution for Robust Bundling

Node resolve is a core concern when bundling with Rollup, especially for libraries and applications that rely on Node.js built-ins, peer dependencies, or complex package.json exports and imports fields. This article walks through pragmatic usage patterns, behavior, and configuration options to ensure your bundle behaves predictably across environments.

Understanding the role of node-resolve in Rollup

The plugin adds Node-like resolution to Rollup, enabling it to locate modules as Node would at runtime. It supports package entrypoints via the exports or imports fields in package.json, and integrates with browser and server environments through conditional exports. This is the default behavior of the plugin, which ensures that import paths are mapped to actual files or built-ins used by Node or the browser.

Externalizing dependencies to slim down bundles

One practical use-case is marking certain dependencies as external so they are not bundled. For example, when building a library with a peer dependency like React or Lodash, you can bundle only your code and let the consumer provide the peer. This can be achieved by configuring the external option in Rollup. The external key accepts either an array of module names or a function that takes the module name and returns true if it should be external. If you are using babel-plugin-lodash to cherry-pick lodash modules, you might treat lodash as external to avoid bundling it entirely.

Voilà, lodash will now be treated as external, and not be bundled with your library. The plugin also supports fine-grained control over which imports are bundled and which are external, enabling highly optimized builds.

CommonJS interop and Babel integration

In many ecosystems, most NPM packages are still exposed as CommonJS modules. Rollup’s node-resolve plugin, when used in combination with the CommonJS plugin, helps Rollup interoperate by converting CommonJS modules to ES modules for the bundle. If you’re using the Babel plugin, place it before the commonjs one to ensure correct transformation order and compatibility with your target environment.

Configuring resolution behavior

Resolution behavior can be customized with several options. Here are key patterns and their typical usage:

  • Package entrypoints: The plugin supports the package entrypoints feature from Node.js, as specified in the exports or imports field of a package. This allows precise control over which file is resolved for a given import path.
  • Export conditions: By default, the plugin looks for the ['default', 'module', 'import', 'development|production'] conditions when resolving imports. You can add extra conditions on top by setting options to tailor resolution for your target environment.
  • Browser resolutions: If true, instructs the plugin to use browser module resolutions in package.json and adds 'browser' to exportConditions if it is not present so browser conditionals in exports are applied. If false, browser properties are ignored.
  • Additional lookup paths: An array of absolute paths to search for modules beyond the standard node_modules resolution.
  • Forced resolution: An array of module names to force resolving for the specified modules to the root node_modules, ensuring consistent deduplication across packages.
  • Package.json fields: A list of properties to scan within a package.json to determine the bundle entry point. The first-found property is used as the resolved entry point, making the resolution deterministic in presence of multiple fields.
  • Prefer built-ins: By default, the plugin favors built-in modules (e.g., fs, path). You can pass a function that returns a boolean to override this behavior, allowing runtime-determined preferences.
  • Side effects: If your package.json uses the sideEffects property, resolution respects it by default for root files, aiding tree-shaking and correct bundling behavior.
  • Node built-ins polyfills: To provide stubbed versions of Node built-ins in the browser, use a plugin like rollup-plugin-node-polyfills and set preferBuiltins to false.
  • Post-resolution step: After an import id is resolved to its target file in node_modules, the plugin will invoke the resolver again with the resolved id to ensure proper depth resolution and chaining.

Practical workflow: integrating node-resolve with Babel and CJS

When building libraries that target both Node and browser environments, you might configure Rollup with the following typical flow:

  • Place babel-plugin-lodash or other Babel plugins before the commonjs plugin if using the latter to transform CommonJS modules to ES modules.
  • Use the external option to declare peer dependencies, ensuring they are not bundled but expected at runtime by the consumer.
  • Leverage the package.json exports and imports fields in dependencies to resolve modern module formats and conditional exports.

In practice, this results in a bundle that remains compatible with Node.js runtimes since the import declaration can be turned into a CommonJS require statement where appropriate, while not forcing the inclusion of peer dependencies or optional internal shims that would bloat the bundle.

Illustrative example: configuring Rollup for a library

import resolve from '@rollup/plugin-node-resolve';import commonjs from '@rollup/plugin-commonjs';import babel from '@rollup/plugin-babel';export default { input: 'src/main.js', external: ['react', 'lodash'], // peer dependencies plugins: [ resolve({ browser: false, preferBuiltins: true, mainFields: ['main', 'module', 'jsnext:main', 'browser'], exportsFields: ['exports'], }), babel({ babelHelpers: 'bundled', include: ['src/**'], exclude: 'node_modules/**', }), commonjs(), ], output: { file: 'dist/bundle.js', format: 'cjs', },};

This setup allows the library to be consumed in environments that provide React and Lodash externally, while Rollup resolves internal dependencies using node-resolve and converts CommonJS modules via the commonjs plugin. The Babel configuration helps optimize code with cherry-picks and modern syntax, while keeping Node compatibility.

Notes on constraints and best practices

  • Keep peer dependencies accurate to avoid runtime missing modules in consumer environments.
  • Be mindful of the exports field behavior in dependencies; not all packages ship with comprehensive exports maps.
  • When targeting browsers, enable browser-specific resolutions or add browser-specific shims as needed to ensure consistent behavior.
  • Avoid overusing external for all dependencies; reserve it for truly external runtime expectations to maximize bundle usefulness.

Additional options and advanced usage

Advanced users may tailor resolution with a functional external resolver to compute externals dynamically based on the import path. This can be useful when you want to treat certain modules as external only under specific conditions or environments. The flexibility of node-resolve, combined with Rollup's plugin ecosystem, provides granular control over how modules are located, transformed, and included in the final bundle.

Node resolution flow diagram

Color Grading Workflows With Nodes In DaVinci Resolve 9

tags: #rollup #plugin #node #resolve