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