feat(node-resolve): allow preferBuiltins to be a function (#1694)

* feat: allow `options.preferBuiltins` to be function

* docs: update readme

* feat: add types in dts

* tests: add testcase about passing function to preferBuiltins

packages/node-resolve/README.md

@@ -133,11 +133,19 @@ Specifies the properties to scan within a `package.json`, used to determine the
 
 ### `preferBuiltins`
 
-Type: `Boolean`<br>
+Type: `Boolean | (module: string) => boolean`<br>
 Default: `true` (with warnings if a builtin module is used over a local version. Set to `true` to disable warning.)
 
 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.
 
+Alternatively, you may pass in a function that returns a boolean to confirm whether the plugin should prefer built-in modules. e.g.
+
+```js
+preferBuiltins: (module) => module !== 'punycode';
+```
+
+will not treat `punycode` as a built-in module
+
 ### `modulesOnly`
 
 Type: `Boolean`<br>

packages/node-resolve/src/index.js

@@ -58,7 +58,7 @@ export function nodeResolve(opts = {}) {
  const idToPackageInfo = new Map();
  const mainFields = getMainFields(options);
  const useBrowserOverrides = mainFields.indexOf('browser') !== -1;
- const isPreferBuiltinsSet = options.preferBuiltins === true || options.preferBuiltins === false;
+ const isPreferBuiltinsSet = Object.prototype.hasOwnProperty.call(options, 'preferBuiltins');
  const preferBuiltins = isPreferBuiltinsSet ? options.preferBuiltins : true;
  const rootDir = resolve(options.rootDir || process.cwd());
  let { dedupe } = options;
@@ -194,8 +194,10 @@ export function nodeResolve(opts = {}) {
  });
 
  const importeeIsBuiltin = builtinModules.includes(importee.replace(nodeImportPrefix, ''));
+ const preferImporteeIsBuiltin =
+ typeof preferBuiltins === 'function' ? preferBuiltins(importee) : preferBuiltins;
  const resolved =
- importeeIsBuiltin && preferBuiltins
+ importeeIsBuiltin && preferImporteeIsBuiltin
  ? {
  packageInfo: undefined,
  hasModuleSideEffects: () => null,
@@ -230,11 +232,14 @@ export function nodeResolve(opts = {}) {
  idToPackageInfo.set(location, packageInfo);
 
  if (hasPackageEntry) {
- if (importeeIsBuiltin && preferBuiltins) {
+ if (importeeIsBuiltin && preferImporteeIsBuiltin) {
  if (!isPreferBuiltinsSet && resolvedWithoutBuiltins && resolved !== importee) {
- context.warn(
- `preferring built-in module '${importee}' over local alternative at '${resolvedWithoutBuiltins.location}', pass 'preferBuiltins: false' to disable this behavior or 'preferBuiltins: true' to disable this warning`
- );
+ context.warn({
+ message:
+ `preferring built-in module '${importee}' over local alternative at '${resolvedWithoutBuiltins.location}', pass 'preferBuiltins: false' to disable this behavior or 'preferBuiltins: true' to disable this warning.` +
+ `or passing a function to 'preferBuiltins' to provide more fine-grained control over which built-in modules to prefer.`,
+ pluginCode: 'PREFER_BUILTINS'
+ });
  }
  return false;
  } else if (jail && location.indexOf(normalize(jail.trim(sep))) !== 0) {

packages/node-resolve/test/fixtures/prefer-builtin-local-and-builtin.js

@@ -0,0 +1,4 @@
+import { sep } from 'path';
+import events from 'events';
+
+export default { sep, events };

packages/node-resolve/test/prefer-builtins.js

@@ -30,13 +30,12 @@ test('handles importing builtins', async (t) => {
 });
 
 test('warning when preferring a builtin module, no explicit configuration', async (t) => {
- let warning = null;
+ let warning = '';
  await rollup({
  input: 'prefer-builtin.js',
- onwarn({ message }) {
- // eslint-disable-next-line no-bitwise
- if (~message.indexOf('preferring')) {
- warning = message;
+ onwarn({ message, pluginCode }) {
+ if (pluginCode === 'PREFER_BUILTINS') {
+ warning += message;
  }
  },
  plugins: [nodeResolve()]
@@ -47,7 +46,8 @@ test('warning when preferring a builtin module, no explicit configuration', asyn
  warning,
  `preferring built-in module 'events' over local alternative ` +
  `at '${localPath}', pass 'preferBuiltins: false' to disable this behavior ` +
- `or 'preferBuiltins: true' to disable this warning`
+ `or 'preferBuiltins: true' to disable this warning.` +
+ `or passing a function to 'preferBuiltins' to provide more fine-grained control over which built-in modules to prefer.`
  );
 });
 
@@ -134,3 +134,27 @@ test('detects builtins imported with node: protocol', async (t) => {
 
  t.is(warnings.length, 0);
 });
+
+test('accpet passing a function to determine which builtins to prefer', async (t) => {
+ const warnings = [];
+ const bundle = await rollup({
+ input: 'prefer-builtin-local-and-builtin.js',
+ onwarn({ message }) {
+ warnings.push(message);
+ },
+ plugins: [
+ nodeResolve({
+ preferBuiltins: (id) => id !== 'events'
+ })
+ ]
+ });
+
+ const {
+ module: { exports }
+ } = await testBundle(t, bundle);
+
+ t.is(warnings.length, 0);
+ t.is(exports.sep, require('node:path').sep);
+ t.not(exports.events, require('node:events'));
+ t.is(exports.events, 'not the built-in events module');
+});

packages/node-resolve/types/index.d.ts

@@ -79,9 +79,11 @@ export interface RollupNodeResolveOptions {
  /**
  * 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.
+ *
+ * If a function is provided, it will be called to determine whether to prefer built-ins.
  * @default true
  */
- preferBuiltins?: boolean;
+ preferBuiltins?: boolean | ((module: string) => boolean);
 
  /**
  * An `Array` which instructs the plugin to limit module resolution to those whose