package-adoption

Find out where a ts/js package is used across a GitHub organization, version and position of the package for each repository.

Usage for pkgName will be analyzed across org, excluding repositories that did not receive any commit in the last daysUntilStale days. A GitHub personal access token with scope repo is required, to access the org private repositories through GitHub APIs. It can be omitted to search across public repositories. Archived repositories are filtered out.

Warning

GitHub API are rate limited, and search API in particular has the additional secondary rate limit. package-adoption implements the best practices guidelines to deal with it, but you should know that limitations could happen in any case.

Caution

GitHub search API are not 100% reliable and sometimes return deleted / outdated files or multiple versions of the same file. The library version in the output could be inaccurate for this reason.

Install

npm install package-adoption

Usage

import { getFilteredReposWithPackageForOrg } from 'package-adoption';

const result = getFilteredReposWithPackageForOrg({
  org: 'my-org',
  daysUntilStale: 90,
  ghAuthToken: 'my-gh-auth-token',
  pkgName: 'my-pkg',
});
/* => [
  {
    name: 'repo-1',
    installationPath: 'root',
    libVersion: '55.0.0-beta.13',
  },
  {
    name: 'repo-2',
    installationPath: 'packages/package-name1',
    libVersion: '65.2.0',
    "isPeerDep": true,
    "isDevDep": true
  },
  {
    name: 'repo-2',
    installationPath: 'packages/package-name2',
    libVersion: '65.2.1',
    "isDevDep": true
  }
]; */

Run CLI

npx package-adoption

package-adoption --config /path/to/config.json --output /path/to/output.json

If output file path omitted, package-adoption outputs to stdout. When config option omitted, the default config file is a local config.json. Copy the committed template to create it:

cp config.example config.json

config.json is git-ignored, so your token stays out of the repository. Fill in org, ghAuthToken, and pkgName:

{
  "org": "myOrg",
  "daysUntilStale": 90,
  "ghAuthToken": "my-GH-auth-token",
  "pkgName": "myPkg"
}

Omit daysUntilStale to use the default of 365.

With inline arguments

package-adoption --org=myOrg --token=my-GH-auth-token --pkg=myPkg --output /path/to/output.json

Run locally

npm run dev reads config.json from the repository root, so create it first:

cp config.example config.json
npm run dev

The CLI falls back to the --org, --token and --pkg arguments when the file is missing. Supply neither and it exits with ENOENT: no such file or directory, open '.../config.json'.