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, default for config file will be local config.json. The file must export an object like this:

{
  "org": "myOrg",
  "daysUntilStale": 90, // If omitted, 365 will be used as default
  "ghAuthToken": "my-GH-auth-token",
  "pkgName": "myPkg"
}

With inline arguments

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

Run locally

npm run dev