@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

mainFields

Type: Array[String]
Default: ['module', 'main']

The fields to scan in a package.json to determine the entry point if this list contains "browser", overrides specified in "pkg.browser" will be used

module

Type: Boolean
Default: true

DEPRECATED: use "mainFields" instead Use "module" field for ES6 module if possible

jsnext

Type: Boolean
Default: false

DEPRECATED: use "mainFields" instead Use "jsnext:main" if possible, legacy field pointing to ES6 module in third-party libraries, deprecated in favor of "pkg.module", see: https://github.com/rollup/rollup/wiki/pkg.module

main

Type: Boolean
Default: true

DEPRECATED: use "mainFields" instead Use "main" field or index.js, even if it's not an ES6 module (needs to be converted from CommonJS to ES6) – see https://github.com/rollup/rollup-plugin-commonjs

browser

Type: Boolean
Default: false

Some package.json files have a "browser" field which specifies alternative files to load for people bundling for the browser. If that's you, either use this option or add "browser" to the "mainFields" option, otherwise pkg.browser will be ignored

extensions

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

Resolve extensions other than .js in the order specified.

preferBuiltins

Type: Boolean
Default: true

Whether to prefer built-in modules (e.g. fs, path) or local ones with the same names

jail

Type: String
Default: '/'

Lock the module search in this path (like a chroot). Modules defined outside this path will be marked as external.

only

Type: Array[String|RegExp]
Default: null

Example: only: ['some_module', /^@some_scope\/.*$/]

modulesOnly

Type: Boolean
Default: false

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

dedupe

Type: Array[String]
Default: []

Force resolving for these modules to root's node_modules that helps to prevent bundling the same package multiple times if package is imported from dependencies.

dedupe: [ 'react', 'react-dom' ]

customResolveOptions

Type: Boolean
Default: null

Any additional options that should be passed through to node-resolve.

customResolveOptions: {
  moduleDirectory: 'js_modules'
}

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-builtins 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)