find-plugins

find-plugins

A simple tool to find installed npm packages that meet certain criteria. Great for finding installed plugins or complementary packages to yours.

Usage

Simple

// Looks up the package.json in process.cwd, and returns any dependencies
// listed that have your package's `name` in their keywords.
plugins = findPlugins();

Custom Keyword

// Same as above, but rather than using your package.json name as the keyword
// to search for, it will look for dependencies with "plugin" in their keyword
// list.
plugins = findPlugins({
    keyword: 'plugin'
});

Custom Filter

// This time, the supplied filter function will be called for each dependency,
// and only those that return true will be returned in the final array.
//
// The filter function is supplied the package.json of the dependency to check.
// In this case, this will find all dependencies whose name starts with
// "my-plugin-"
plugins = findPlugins({
    filter: function(pkg) {
        return /^my-plugin-/.test(pkg.name);
    }
});

Ignore package.json dependency list

// The scanAllDirs option allows you to skip loading your app's package.json
// dependency list. Instead, it will scan all directories in the node_modules
// folder, regardless of whether they are listed as dependencies or not.
plugins = findPlugins({
    scanAllDirs: true
});

Specify node_modules directory and your package.json

// Got an unusual setup? Just pass in the path of the directory containing your
// dependencies, and the path to your app's package.json file. `pkg` is
// optional if you are using `scanAllDirs` and `keyword` or `filter`.
plugins = findPlugins({
    dir: path.join('..', 'foo', 'bar', 'node_modules'),
    pkg: path.join('..', 'foo', 'bar', 'package.json')
});

Sort the plugins based on "before" and "after" config in their package.json's

// Each plugin can optionally include a "plugin-config" (or whatever you pass in under `configName`)
// with a "before" and/or "after" property. These can be the name of another plugin (or an array of
// other plugin names) that this plugin should come before/after. The returned array will be sorted
// according to these rules via a directed acyclic graph
plugins = findPlugins({
    sort: true,
    configName: 'plugin-config'
});

Options

{

  /**
   * The node_modules directory to scan for plugins
   *
   * @type {string}
   */
  dir?: string = process.cwd(),

  /**
   * The path to the package.json that lists dependencies to check for plugins
   *
   * @type {string}
   */
  pkg?: string = './package.json',

  /**
   * An array of additional paths to check as plugins
   *
   * @type {string[]}
   */
  include?: string[] = [],

  /**
   * If supplied, a package will be considered a plugin if `keyword` is present in it's package.json
   * "keywords" array
   *
   * @type {string}
   */
  keyword?: string = pkg.name,

  /**
   * If sort: true is supplied, this determines what property of the plugin's package.json to check
   * for the sort configuration (it should be an object with "before" and "after" properties which
   * are arrays of other plugins names)
   *
   * @type {boolean}
   */
  sort?: boolean = false,

  /**
   * The property on a plugin's package.json that contains sort config (an object with "before"
   * and/or "after" properties, which are the names of the plugin, or arrays of names)
   *
   * @type {string}
   */
  configName?: string = pkg.name,

  /**
   * A custom filter function that will receive the package summary and should return a boolean
   * indicating whether or not that package is a plugin.
   *
   * @type {function}
   */
  filter?: (plugin: PluginSummary) => boolean,

  /**
   * If true, the package.json list of dependencies will be ignored, and all packages found in
   * dir will be checked.
   *
   * @type {boolean}
   */
  scanAllDirs?: boolean,

  /**
   * By default, findPlugins checks only the packages listed under "dependencies" in the
   * package.json. Setting this option to true will ignore those packages listed under
   * "dependencies".
   *
   * @type {boolean}
   */
  excludeDependencies?: boolean,

  /**
   * Also check packages listed under devDependencies
   *
   * @type {boolean}
   */
  includeDev?: boolean,

  /**
   * Also check packages listed under peerDependencies
   *
   * @type {boolean}
   */
  includePeer?: boolean,

  /**
   * Also check packages listed under bundleDependencies
   *
   * @type {boolean}
   */
  includeBundle?: boolean,

  /**
   * Also check packages listed under optionalDependencies
   *
   * @type {boolean}
   */
  includeOptional?: boolean

}

Returns

> findPlugins();
[
    {
        dir: './node_modules/foobar',
        pkg: { name: 'foobar', version: '0.0.1', ... }
    },
    ...
]