1 | [npm]: https://img.shields.io/npm/v/@rollup/plugin-node-resolve
|
2 | [npm-url]: https://www.npmjs.com/package/@rollup/plugin-node-resolve
|
3 | [size]: https://packagephobia.now.sh/badge?p=@rollup/plugin-node-resolve
|
4 | [size-url]: https://packagephobia.now.sh/result?p=@rollup/plugin-node-resolve
|
5 |
|
6 | [![npm][npm]][npm-url]
|
7 | [![size][size]][size-url]
|
8 | [![libera manifesto](https://img.shields.io/badge/libera-manifesto-lightgrey.svg)](https://liberamanifesto.com)
|
9 |
|
10 | # @rollup/plugin-node-resolve
|
11 |
|
12 | 🍣 A Rollup plugin which locates modules using the [Node resolution algorithm](https://nodejs.org/api/modules.html#modules_all_together), for using third party modules in `node_modules`
|
13 |
|
14 | ## Requirements
|
15 |
|
16 | This plugin requires an [LTS](https://github.com/nodejs/Release) Node version (v8.0.0+) and Rollup v1.20.0+.
|
17 |
|
18 | ## Install
|
19 |
|
20 | Using npm:
|
21 |
|
22 | ```console
|
23 | npm install @rollup/plugin-node-resolve --save-dev
|
24 | ```
|
25 |
|
26 | ## Usage
|
27 |
|
28 | Create a `rollup.config.js` [configuration file](https://www.rollupjs.org/guide/en/#configuration-files) and import the plugin:
|
29 |
|
30 | ```js
|
31 | import { nodeResolve } from '@rollup/plugin-node-resolve';
|
32 |
|
33 | export default {
|
34 | input: 'src/index.js',
|
35 | output: {
|
36 | dir: 'output',
|
37 | format: 'cjs'
|
38 | },
|
39 | plugins: [nodeResolve()]
|
40 | };
|
41 | ```
|
42 |
|
43 | Then call `rollup` either via the [CLI](https://www.rollupjs.org/guide/en/#command-line-reference) or the [API](https://www.rollupjs.org/guide/en/#javascript-api).
|
44 |
|
45 | ## Options
|
46 |
|
47 | ### `exportConditions`
|
48 |
|
49 | Type: `Array[...String]`<br>
|
50 | Default: `[]`
|
51 |
|
52 | Additional conditions of the package.json exports field to match when resolving modules. By default, this plugin looks for the `['default', 'module', 'import']` conditions when resolving imports.
|
53 |
|
54 | When using `@rollup/plugin-commonjs` v16 or higher, this plugin will use the `['default', 'module', 'require']` conditions when resolving require statements.
|
55 |
|
56 | Setting this option will add extra conditions on top of the default conditions. See https://nodejs.org/api/packages.html#packages_conditional_exports for more information.
|
57 |
|
58 | ### `browser`
|
59 |
|
60 | Type: `Boolean`<br>
|
61 | Default: `false`
|
62 |
|
63 | 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`.
|
64 |
|
65 | ### `moduleDirectories`
|
66 |
|
67 | Type: `Array[...String]`<br>
|
68 | Default: `['node_modules']`
|
69 |
|
70 | One or more directories in which to recursively look for modules.
|
71 |
|
72 | ### `dedupe`
|
73 |
|
74 | Type: `Array[...String]`<br>
|
75 | Default: `[]`
|
76 |
|
77 | 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.
|
78 |
|
79 | ```js
|
80 | dedupe: ['my-package', '@namespace/my-package'];
|
81 | ```
|
82 |
|
83 | This will deduplicate bare imports such as:
|
84 |
|
85 | ```js
|
86 | import 'my-package';
|
87 | import '@namespace/my-package';
|
88 | ```
|
89 |
|
90 | And it will deduplicate deep imports such as:
|
91 |
|
92 | ```js
|
93 | import 'my-package/foo.js';
|
94 | import '@namespace/my-package/bar.js';
|
95 | ```
|
96 |
|
97 | ### `extensions`
|
98 |
|
99 | Type: `Array[...String]`<br>
|
100 | Default: `['.mjs', '.js', '.json', '.node']`
|
101 |
|
102 | Specifies the extensions of files that the plugin will operate on.
|
103 |
|
104 | ### `jail`
|
105 |
|
106 | Type: `String`<br>
|
107 | Default: `'/'`
|
108 |
|
109 | Locks the module search within specified path (e.g. chroot). Modules defined outside this path will be ignored by this plugin.
|
110 |
|
111 | ### `mainFields`
|
112 |
|
113 | Type: `Array[...String]`<br>
|
114 | Default: `['module', 'main']`<br>
|
115 | Valid values: `['browser', 'jsnext:main', 'module', 'main']`
|
116 |
|
117 | 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.
|
118 |
|
119 | ### `preferBuiltins`
|
120 |
|
121 | Type: `Boolean`<br>
|
122 | Default: `true` (with warnings if a builtin module is used over a local version. Set to `true` to disable warning.)
|
123 |
|
124 | 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.
|
125 |
|
126 | ### `modulesOnly`
|
127 |
|
128 | Type: `Boolean`<br>
|
129 | Default: `false`
|
130 |
|
131 | If `true`, inspect resolved files to assert that they are ES2015 modules.
|
132 |
|
133 | ### `resolveOnly`
|
134 |
|
135 | Type: `Array[...String|RegExp]`<br>
|
136 | Default: `null`
|
137 |
|
138 | 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._
|
139 |
|
140 | Example: `resolveOnly: ['batman', /^@batcave\/.*$/]`
|
141 |
|
142 | ### `rootDir`
|
143 |
|
144 | Type: `String`<br>
|
145 | Default: `process.cwd()`
|
146 |
|
147 | 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.
|
148 |
|
149 | ```
|
150 | // Set the root directory to be the parent folder
|
151 | rootDir: path.join(process.cwd(), '..')
|
152 | ```
|
153 |
|
154 | ## Preserving symlinks
|
155 |
|
156 | This plugin honours the rollup [`preserveSymlinks`](https://rollupjs.org/guide/en/#preservesymlinks) option.
|
157 |
|
158 | ## Using with @rollup/plugin-commonjs
|
159 |
|
160 | Since most packages in your node_modules folder are probably legacy CommonJS rather than JavaScript modules, you may need to use [@rollup/plugin-commonjs](https://github.com/rollup/plugins/tree/master/packages/commonjs):
|
161 |
|
162 | ```js
|
163 | // rollup.config.js
|
164 | import { nodeResolve } from '@rollup/plugin-node-resolve';
|
165 | import commonjs from '@rollup/plugin-commonjs';
|
166 |
|
167 | export default {
|
168 | input: 'main.js',
|
169 | output: {
|
170 | file: 'bundle.js',
|
171 | format: 'iife',
|
172 | name: 'MyModule'
|
173 | },
|
174 | plugins: [nodeResolve(), commonjs()]
|
175 | };
|
176 | ```
|
177 |
|
178 | ## Resolving Built-Ins (like `fs`)
|
179 |
|
180 | By default this plugin will prefer built-ins over local modules, marking them as external.
|
181 |
|
182 | See [`preferBuiltins`](#preferbuiltins).
|
183 |
|
184 | To provide stubbed versions of Node built-ins, yse a plugin like [rollup-plugin-node-polyfills](https://github.com/ionic-team/rollup-plugin-node-polyfills) or use [`builtin-modules`](https://github.com/sindresorhus/builtin-modules) with `external`, and set `preferBuiltins` to `false`. e.g.
|
185 |
|
186 | ```js
|
187 | import { nodeResolve } from '@rollup/plugin-node-resolve';
|
188 | import builtins from 'builtin-modules'
|
189 | export default ({
|
190 | input: ...,
|
191 | plugins: [nodeResolve()],
|
192 | external: builtins,
|
193 | output: ...
|
194 | })
|
195 | ```
|
196 |
|
197 | ## Resolving require statements
|
198 |
|
199 | According to [NodeJS module resolution](https://nodejs.org/api/packages.html#packages_package_entry_points) `require` statements should resolve using the `require` condition in the package exports field, while es modules should use the `import` condition.
|
200 |
|
201 | The node resolve plugin uses `import` by default, you can opt into using the `require` semantics by passing an extra option to the resolve function:
|
202 |
|
203 | ```js
|
204 | this.resolve(importee, importer, {
|
205 | skipSelf: true,
|
206 | custom: { 'node-resolve': { isRequire: true } }
|
207 | });
|
208 | ```
|
209 |
|
210 | ## Meta
|
211 |
|
212 | [CONTRIBUTING](/.github/CONTRIBUTING.md)
|
213 |
|
214 | [LICENSE (MIT)](/LICENSE)
|