@rollup/plugin-node-resolve

What is @rollup/plugin-node-resolve?

The @rollup/plugin-node-resolve package is a plugin for Rollup that allows it to resolve node_modules on your behalf, similar to how Node.js would work. It helps in bundling packages with Rollup by locating and bundling third-party dependencies from the node_modules directory.

What are @rollup/plugin-node-resolve's main functionalities?

Resolving modules from node_modules

Automatically resolves modules from the node_modules directory, allowing you to import dependencies in your project.

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

export default {
  plugins: [
    resolve()
  ]
};

Custom resolution for specific modules

Allows you to specify custom resolution options for modules, such as looking in different directories.

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

export default {
  plugins: [
    resolve({
      customResolveOptions: {
        moduleDirectory: 'custom_modules'
      }
    })
  ]
};

Browser field support for package.json

Respects the 'browser' field in package.json when bundling packages, which can specify alternative files to load for certain environments.

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

export default {
  plugins: [
    resolve({
      browser: true
    })
  ]
};

Main fields configuration

Allows configuration of which fields in package.json files it should look at when trying to resolve an import.

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

export default {
  plugins: [
    resolve({
      mainFields: ['module', 'main']
    })
  ]
};

Other packages similar to @rollup/plugin-node-resolve

webpack

Webpack is a powerful module bundler that comes with its own resolution mechanism similar to @rollup/plugin-node-resolve. It resolves modules by default and can be configured extensively via its configuration file.

browserify

Browserify is another bundler that allows you to require('modules') in the browser by bundling up all of your dependencies. It also has a resolution mechanism similar to Node.js, much like @rollup/plugin-node-resolve.

parcel-bundler

Parcel is a web application bundler that has zero configuration by default and includes a powerful module resolution system that works out of the box, similar to @rollup/plugin-node-resolve.

README

@rollup/plugin-node-resolve

🍣 A Rollup plugin which locates modules using the Node resolution algorithm, for using third party modules in node_modules

Requirements

This plugin requires an LTS Node version (v8.0.0+) and Rollup v1.20.0+.

Install

Using npm:

npm install @rollup/plugin-node-resolve --save-dev

Usage

Create a rollup.config.js configuration file and import the plugin:

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

export default {
  input: 'src/index.js',
  output: {
    dir: 'output',
    format: 'cjs'
  },
  plugins: [resolve()]
};

Then call rollup either via the CLI or the API.

Options

browser

Type: Boolean
Default: false

If true, instructs the plugin to use the "browser" property in package.json files to specify alternative files to load for bundling. This is useful when bundling for a browser environment. Alternatively, a value of 'browser' can be added to the mainFields option. If false, any "browser" properties in package files will be ignored. This option takes precedence over mainFields.

customResolveOptions

Type: Boolean
Default: null

An Object that specifies additional options that should be passed through to node-resolve.

customResolveOptions: {
  moduleDirectory: 'js_modules'
}

dedupe

Type: Array[...String]
Default: []

An Array of modules names, which instructs the plugin to force resolving for the specified modules to the root node_modules. Helps to prevent bundling the same package multiple times if package is imported from dependencies.

dedupe: ['my-package', '@namespace/my-package'];

This will deduplicate bare imports such as:

import 'my-package';
import '@namespace/my-package';

And it will deduplicate deep imports such as:

import 'my-package/foo.js';
import '@namespace/my-package/bar.js';

extensions

Type: Array[...String]
Default: ['.mjs', '.js', '.json', '.node']

Specifies the extensions of files that the plugin will operate on.

jail

Type: String
Default: '/'

Locks the module search within specified path (e.g. chroot). Modules defined outside this path will be marked as external.

mainFields

Type: Array[...String]
Default: ['module', 'main']
Valid values: ['browser', 'jsnext', 'module', 'main']

Specifies the properties to scan within a package.json, used to determine the bundle entry point. The order of property names is significant, as the first-found property is used as the resolved entry point. If the array contains 'browser', key/values specified in the package.json browser property will be used.

only

DEPRECATED: use "resolveOnly" instead

preferBuiltins

Type: Boolean
Default: true

If true, the plugin will prefer built-in modules (e.g. fs, path). If false, the plugin will look for locally installed modules of the same name.

modulesOnly

Type: Boolean
Default: false

If true, inspect resolved files to assert that they are ES2015 modules.

resolveOnly

Type: Array[...String|RegExp]
Default: null

An Array which instructs the plugin to limit module resolution to those whose names match patterns in the array. Note: Modules not matching any patterns will be marked as external.

Example: resolveOnly: ['batman', /^@batcave\/.*$/]

rootDir

Type: String
Default: process.cwd()

Specifies the root directory from which to resolve modules. Typically used when resolving entry-point imports, and when resolving deduplicated modules. Useful when executing rollup in a package of a mono-repository.

// Set the root directory to be the parent folder
rootDir: path.join(process.cwd(), '..')

Using with @rollup/plugin-commonjs

Since most packages in your node_modules folder are probably legacy CommonJS rather than JavaScript modules, you may need to use @rollup/plugin-commonjs:

// rollup.config.js
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

export default {
  input: 'main.js',
  output: {
    file: 'bundle.js',
    format: 'iife',
    name: 'MyModule'
  },
  plugins: [resolve(), commonjs()]
};

Resolving Built-Ins (like fs)

This plugin won't resolve any builtins (e.g. fs). If you need to resolve builtins you can install local modules and set preferBuiltins to false, or install a plugin like rollup-plugin-node-polyfills which provides stubbed versions of these methods.

If you want to silence warnings about builtins, you can add the list of builtins to the externals option; like so:

import resolve from '@rollup/plugin-node-resolve';
import builtins from 'builtin-modules'
export default ({
  input: ...,
  plugins: [resolve()],
  external: builtins,
  output: ...
})

Meta

CONTRIBUTING

LICENSE (MIT)