load-plugin

Load a submodule, plugin, or file. Like Node’s require and require.resolve, but from one or more places, and optionally global too.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install load-plugin

Use

Say we’re in this project (with dependencies installed):

import {loadPlugin, resolvePlugin} from 'load-plugin'

main()

async function main() {
  await resolvePlugin('lint', {prefix: 'remark'})
  // => '/Users/tilde/projects/oss/load-plugin/node_modules/remark-lint/index.js'

  await resolvePlugin('@babel/function-name', {prefix: 'helper'})
  // => '/Users/tilde/projects/oss/load-plugin/node_modules/@babel/helper-function-name/lib/index.js'

  await resolvePlugin('./index.js', {prefix: 'remark'})
  // => '/Users/tilde/projects/oss/load-plugin/index.js'

  await loadPlugin('lint', {prefix: 'remark'})
  // => [Function: lint]
}

API

This package exports the following identifiers: loadPlugin, resolvePlugin. There is no default export.

loadPlugin(name[, options])

Uses Node’s resolution algorithm (through import-meta-resolve) to load CJS and ESM packages and files to import name in each given cwd (and optionally the global node_modules directory).

If a prefix is given and name is not a path, $prefix-$name is also searched (preferring these over non-prefixed modules). If name starts with a scope (@scope/name), the prefix is applied after it: @scope/$prefix-name.

options

options.prefix

Prefix to search for (string, optional).

options.cwd

Place or places to search from (string, Array.<string>, default: process.cwd()).

options.global

Whether to look for name in global places (boolean, optional, defaults to whether global is detected). If this is nullish, load-plugin will detect if it’s currently running in global mode: either because it’s in Electron, or because a globally installed package is running it.

Note: Electron runs its own version of Node instead of your system Node. That means global packages cannot be found, unless you’ve set-up a prefix in your .npmrc or are using nvm to manage your system node.

options.key

Identifier to take from the exports (string or false, default: 'default'). For example when given 'whatever', the value of export const whatever = 1 will be returned, when given 'default', the value of export default … is used, and when false the whole module object is returned.

Returns

Promise.<unknown> — Promise yielding the results of requireing the first path that exists. The promise rejects if requireing an existing path fails, or if no existing path exists.

loadPlugin.resolve(name[, options])

Search for name. Accepts the same parameters as loadPlugin (except key) but returns a promise resolving to an absolute path for name instead of importing it. Throws if name cannot be found.

License

MIT © Titus Wormer