Get-addons NPM

get-addons

Reads package.json files to generate a dependency tree of package addons/plugins/presets.

Install

$ npm install get-addons

Import

Node.js / CommonJS:

const { getAddons } = require('get-addons')

ESNext / TypeScript:

import { getAddons } from 'get-addons'

Standard usage

This example will return the tree of all packages that match the following patterns:

@ANY_SCOPED_NAME/babel-plugin
@ANY_SCOPED_NAME/babel-preset
@ANY_SCOPED_NAME/babel-plugin-*
@ANY_SCOPED_NAME/babel-preset-*
babel-plugin-*
babel-preset-*

const addons = getAddons({
  packageName: 'babel' // An array can also be provided
})

Limit to scoped packages only:

const addons = getAddons({
  packageScope: 'babel' // An array can also be provided
})

Omit devDependencies from the tree:

const addons = getAddons({
  // ...
  includeDevDependencies: false
  // ^ Defaults to `true` if `process.env.NODE_ENV` is 'development'
})

Look for package types other than plugins or presets:

const addons = getAddons({
  // ...
  patterns: {
    theme: 'theme'
  }
})

Search for dependency keys other than 'dependencies', 'devDependencies', and 'optionalDependencies':

const addons = getAddons({
  // ...
  dependencyKeys: ['customDependencies']
})

API

getAddons

▸ getAddons(options: Options): PackageInfo[]

Parameters:

Name	Type	Description
options	Options	Options

Returns: PackageInfo[] Object tree of dependencies that match the provided options.

Options

interface Options {
  /**
   * Current working directory.
   *
   * @default `process.cwd()`
   */
  cwd?: string

  /**
   * The dependency fields to read in `package.json`.
   *
   * @default
   * ['dependencies', 'devDependencies', 'optionalDependencies']
   */
  dependencyKeys?: string[]

  /**
   * Whether to include dependencies that start with or include "dev".
   *
   * This option only has an effect for the initial `package.json`.
   * `devDependencies` and unknown future fields with "dev" in the name are
   * never read for nested packages.
   *
   * @default
   * process.env.NODE_ENV === 'development'
   */
  includeDevDependencies?: boolean

  /**
   * The package names to look for.
   *
   * @example
   * "react-native"
   *
   * @example
   * ["react", "react-native"]
   */
  packageName?: string | string[]

  /**
   * First-party package scopes to look for.
   *
   * @example
   * "@babel"
   *
   * @example
   * ["@babel", "@types"]
   */
  packageScope?: string | string[]

  /**
   * Glob patterns
   *
   * The key of the object is considered the addon kind, such as "preset" or
   * "plugin".
   *
   * The key value is the glob pattern(s) to match. Prefix your pattern with an
   * exclamation point to ignore a pattern (example: "!plugin-legacy").
   *
   * **IMPORTANT**
   *
   * **Do not end your pattern with a separator and a wildcard (example: "-*")**.
   * `get-addons` will automatically add in a separator and wildcard as needed.
   *
   * It's also important that consumers of your addon have the ability to use
   * their own scoped version. "babel-preset-foobar" should also work as
   * "@foobar/babel-preset".
   *
   * @example
   * { "theme": "theme" }
   */
  patterns?: {
    [kind: string]: string | string[]
  }

PackageInfo

/**
 * Meta information for each addon package.
 */
interface PackageInfo {
  /**
   * Addons.
   *
   * (For performance purposes, this is defined as a dynamic getter).
   */
  addons: PackageInfo[]

  /**
   * The addon category or classification.
   *
   * @example "plugin"
   */
  kind: string

  /**
   * The dependency fields this package was found within `package.json`.
   *
   * @example
   * ['dependencies', 'optionalDependencies']
   */
  dependencyKeys: string[]

  /**
   * Package name.
   */
  name: string

  /**
   * Absolute path to the package directory.
   *
   * (For performance purposes, this is defined as a dynamic getter).
   */
  path: string

  /**
   * Package version.
   */
  version: string
}