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 resolve 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: [resolve()]
|
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 | ### `browser`
|
48 |
|
49 | Type: `Boolean`<br>
|
50 | Default: `false`
|
51 |
|
52 | 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`.
|
53 |
|
54 | ### `customResolveOptions`
|
55 |
|
56 | Type: `Object`<br>
|
57 | Default: `null`
|
58 |
|
59 | An `Object` that specifies additional options that should be passed through to [`resolve`](https://www.npmjs.com/package/resolve).
|
60 |
|
61 | ```
|
62 | customResolveOptions: {
|
63 | moduleDirectory: 'js_modules'
|
64 | }
|
65 | ```
|
66 |
|
67 | ### `dedupe`
|
68 |
|
69 | Type: `Array[...String]`<br>
|
70 | Default: `[]`
|
71 |
|
72 | 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.
|
73 |
|
74 | ```js
|
75 | dedupe: ['my-package', '@namespace/my-package'];
|
76 | ```
|
77 |
|
78 | This will deduplicate bare imports such as:
|
79 |
|
80 | ```js
|
81 | import 'my-package';
|
82 | import '@namespace/my-package';
|
83 | ```
|
84 |
|
85 | And it will deduplicate deep imports such as:
|
86 |
|
87 | ```js
|
88 | import 'my-package/foo.js';
|
89 | import '@namespace/my-package/bar.js';
|
90 | ```
|
91 |
|
92 | ### `extensions`
|
93 |
|
94 | Type: `Array[...String]`<br>
|
95 | Default: `['.mjs', '.js', '.json', '.node']`
|
96 |
|
97 | Specifies the extensions of files that the plugin will operate on.
|
98 |
|
99 | ### `jail`
|
100 |
|
101 | Type: `String`<br>
|
102 | Default: `'/'`
|
103 |
|
104 | Locks the module search within specified path (e.g. chroot). Modules defined outside this path will be marked as external.
|
105 |
|
106 | ### `mainFields`
|
107 |
|
108 | Type: `Array[...String]`<br>
|
109 | Default: `['module', 'main']`<br>
|
110 | Valid values: `['browser', 'jsnext', 'module', 'main']`
|
111 |
|
112 | 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.
|
113 |
|
114 | ### `only`
|
115 |
|
116 | DEPRECATED: use "resolveOnly" instead
|
117 |
|
118 | ### `preferBuiltins`
|
119 |
|
120 | Type: `Boolean`<br>
|
121 | Default: `true`
|
122 |
|
123 | 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.
|
124 |
|
125 | ### `modulesOnly`
|
126 |
|
127 | Type: `Boolean`<br>
|
128 | Default: `false`
|
129 |
|
130 | If `true`, inspect resolved files to assert that they are ES2015 modules.
|
131 |
|
132 | ### `resolveOnly`
|
133 |
|
134 | Type: `Array[...String|RegExp]`<br>
|
135 | Default: `null`
|
136 |
|
137 | 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._
|
138 |
|
139 | Example: `resolveOnly: ['batman', /^@batcave\/.*$/]`
|
140 |
|
141 | ### `rootDir`
|
142 |
|
143 | Type: `String`<br>
|
144 | Default: `process.cwd()`
|
145 |
|
146 | 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.
|
147 |
|
148 | ```
|
149 | // Set the root directory to be the parent folder
|
150 | rootDir: path.join(process.cwd(), '..')
|
151 | ```
|
152 |
|
153 | ## Using with @rollup/plugin-commonjs
|
154 |
|
155 | 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):
|
156 |
|
157 | ```js
|
158 | // rollup.config.js
|
159 | import resolve from '@rollup/plugin-node-resolve';
|
160 | import commonjs from '@rollup/plugin-commonjs';
|
161 |
|
162 | export default {
|
163 | input: 'main.js',
|
164 | output: {
|
165 | file: 'bundle.js',
|
166 | format: 'iife',
|
167 | name: 'MyModule'
|
168 | },
|
169 | plugins: [resolve(), commonjs()]
|
170 | };
|
171 | ```
|
172 |
|
173 | ## Resolving Built-Ins (like `fs`)
|
174 |
|
175 | 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](https://github.com/ionic-team/rollup-plugin-node-polyfills) which provides stubbed versions of these methods.
|
176 |
|
177 | If you want to silence warnings about builtins, you can add the list of builtins to the `externals` option; like so:
|
178 |
|
179 | ```js
|
180 | import resolve from '@rollup/plugin-node-resolve';
|
181 | import builtins from 'builtin-modules'
|
182 | export default ({
|
183 | input: ...,
|
184 | plugins: [resolve()],
|
185 | external: builtins,
|
186 | output: ...
|
187 | })
|
188 | ```
|
189 |
|
190 | ## Meta
|
191 |
|
192 | [CONTRIBUTING](/.github/CONTRIBUTING.md)
|
193 |
|
194 | [LICENSE (MIT)](/LICENSE)
|