# Open Source Stats

A Bijection Component for syncing and rendering open source project data.

- Package: @bijectionhq/oss-stats
- Category: Integrations
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/oss-stats/tree/09731d8324eff57eb28b573f6303f81cecec74b4
- Upstream: https://github.com/erquhart/convex-oss-stats/tree/8653a3e8d785abe84f13d270ee3b88e872e701fd
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/oss-stats

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/oss-stats.git
cd oss-stats
git checkout 09731d8324eff57eb28b573f6303f81cecec74b4
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes @erquhart/convex-oss-stats; check the Bijection adaptation separately.

This component automatically syncs GitHub stars, dependencies, and npm download statistics for your open source projects directly into your Convex database. It provides real-time updates via GitHub webhooks and includes React hooks for live download counters. You can track entire organizations or individual repositories and packages, with aggregated statistics and forecasting capabilities.

### Use cases

• **Portfolio dashboards** - Display live GitHub star counts and npm download metrics for your open source projects on your personal or company website
• **OSS project analytics** - Track adoption trends across multiple repositories and packages with day-of-week averages and historical data
• **Real-time project monitoring** - Set up automated syncing via webhooks to get instant updates when repositories receive new stars
• **Multi-project aggregation** - Combine statistics from related packages and repositories to show total impact across an entire organization
• **Live download counters** - Use the `useNpmDownloadCounter` hook to display forecasted download counts that update continuously in your UI

### How it works

The component uses GitHub's API with personal access tokens to fetch repository metadata like star counts and dependent counts, while npm statistics are pulled from public npm APIs without authentication. You configure it by specifying `githubOwners`, `npmOrgs`, `githubRepos`, and `npmPackages` in the `OssStats` constructor, then expose the API functions through your Convex backend.

Real-time updates work through GitHub webhooks registered at `/events/github` that trigger automatic data syncing when stars change. For npm data, the component calculates download rate forecasts based on historical patterns. The `useNpmDownloadCounter` React hook provides live-updating download counts with configurable intervals for smooth UI animations.

Data querying happens through standard Convex patterns using `useQuery` on the frontend with functions like `getGithubOwner` and `getNpmOrg`, or directly from backend functions using the `ossStats` client methods. You can also set up manual syncing via cron jobs using the `sync()` function if you prefer not to use webhooks.

### Upstream README

# Convex OSS Stats Component

Keep GitHub and npm data for your open source projects synced to your Convex database.

```ts
// convex/stats.ts
import { components } from "./_generated/api";
import { OssStats } from "@erquhart/convex-oss-stats";

export const ossStats = new OssStats(components.ossStats, {
  // Get stats for entire owners / orgs
  githubOwners: ["get-convex"],
  npmOrgs: ["convex-dev"],
  // Or individual repos / packages
  githubRepos: ["get-convex/convex-js"],
  npmPackages: ["@convex-dev/convex-js"],
});

export const {
  sync,
  clearAndSync,
  getGithubOwner,
  getNpmOrg,
  getGithubRepo,
  getGithubRepos,
  getNpmPackage,
  getNpmPackages,
} = ossStats.api();
```

```tsx
// src/OssStats.tsx
import { useQuery } from "convex/react";
import { useNpmDownloadCounter } from "@erquhart/convex-oss-stats/react";
import { api } from "../convex/_generated/api";

const OssStats = () => {
  const githubOwner = useQuery(api.stats.getGithubOwner, {
    owner: "get-convex",
  });
  const npmOrg = useQuery(api.stats.getNpmOrg, {
    org: "convex-dev",
  });

  // Use this hook to get a forecasted download count for an npm package or org
  const liveNpmDownloadCount = useNpmDownloadCounter(npmOrg);

  return (
    <>
      {/* If webhook is registered, this will update in realtime 🔥 */}
      <div>{githubOwner.starCount}</div>
      <div>{liveNpmDownloadCount.count}</div>
    </>
  );
};
```

## Prerequisites

### Convex App

You'll need a Convex App to use the component. Follow any of the
[Convex quickstarts](https://docs.convex.dev/home) to set one up.

### GitHub Account (if syncing GitHub data)

From your GitHub account, get the following credentials:

- **Access Token**
  - Go to account settings and generate a new access token with read access to
    public repositories.
- **Webhook Secret**: do this for each org or repo.
  - Note: this is optional. Without it, you won't get live star counts.
    See how to [manually sync data below](#manually-syncing-data).
  - Go to the settings for the org/repo and create a new webhook.
  - Get the HTTP Actions URL for your **Production** Convex deployment settings:
    https://dashboard.convex.dev/deployment/settings > HTTP Actions URL
  - Payload URL: `<http-actions-url>/events/github`
  - Content type: `application/json`
  - Generate a secret to share between your Convex deployment and GitHub
  - Which events? > Select individual > Stars only

### Note on npm data

npm data accessed by this component is public and doesn't require any credentials.

## Installation

Install the component package:

```ts
npm install @erquhart/convex-oss-stats
```

Create a `convex.config.ts` file in your app's `convex/` folder and install the component by calling `use`:

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import ossStats from "@erquhart/convex-oss-stats/convex.config";

const app = defineApp();
app.use(ossStats);

export default app;
```

Set your API credentials:

```sh
npx convex env set GITHUB_ACCESS_TOKEN=xxxxx
npx convex env set GITHUB_WEBHOOK_SECRET=xxxxx
```

If you haven't been running `npx convex dev` yet, you'll need to start it now.
It will generate code for the component in your `convex/_generated/api` folder,
and will deploy changes automatically as you change files in `convex/`.

Instantiate an OssStats Component client in a file in your app's `convex/` folder:

```ts
// convex/example.ts
import { OssStats } from "@erquhart/convex-oss-stats";
import { components } from "./_generated/api";

export const ossStats = new OssStats(components.ossStats, {
  githubOwners: ["get-convex"],
  npmOrgs: ["convex-dev"],
});

// Re-export functions for direct access from your convex instance
export const { sync, getGithubOwner, getNpmOrg } = ossStats.api();
```

Register GitHub webhook handlers by creating an `http.ts` file in your `convex/` folder and use the client you've exported above:

```ts
// http.ts
import { ossStats } from "./example";
import { httpRouter } from "convex/server";

const http = httpRouter();

ossStats.registerRoutes(http);
export default http;
```

## Querying data from the frontend

Use the `useQuery` hook to get data from the component. Here's an example of how to get data for a GitHub owner (org or user) and an npm package or org:

```ts
// src/OssStats.tsx
import { useQuery } from 'convex/react'
import { api } from '../convex/_generated/api'

const OssStats = () => {
  const githubOwner = useQuery(api.stats.getGithubOwner, {
    owner: 'get-convex',
  })
  const npmOrg = useQuery(api.stats.getNpmOrg, {
    org: 'convex-dev',
  })

  return (
    <>
      {/* If webhook is registered, this will update in realtime 🔥 */}
      <div>{githubOwner.starCount}</div>
      <div>{npmOrg.downloadCount}</div>
    </>
  )
}
```

### Available queries

#### `stats.getGithubOwner`

```ts
const { starCount, dependentCount, dayOfWeekAverages, updatedAt } = useQuery(
  api.stats.getGithubOwner,
  { owner: "get-convex" }
);
```

#### `stats.getNpmOrg`

```ts
const { downloadCount, dayOfWeekAverages, updatedAt } = useQuery(
  api.stats.getNpmOrg,
  { org: "convex-dev" }
);
```

#### `stats.getGithubRepo`

```ts
const { starCount, dependentCount, dayOfWeekAverages, updatedAt } = useQuery(
  api.stats.getGithubRepo,
  { name: "get-convex/convex-js" }
);
```

#### `stats.getGithubRepos`

```ts
const { starCount, dependentCount, dayOfWeekAverages, updatedAt } = useQuery(
  api.stats.getGithubRepos,
  { names: ["get-convex/convex-js", "get-convex/convex-helpers"] }
);
```

#### `stats.getNpmPackage`

```ts
const { downloadCount, dayOfWeekAverages, updatedAt } = useQuery(
  api.stats.getNpmPackage,
  { name: "@convex-dev/convex-js" }
);
```

#### `stats.getNpmPackages`

```ts
const { downloadCount, dayOfWeekAverages, updatedAt } = useQuery(
  api.stats.getNpmPackages,
  { names: ["@convex-dev/convex-js", "@convex-dev/convex-helpers"] }
);
```

### React hooks

#### `useNpmDownloadCounter`

Provides a forecasted download count for an npm package or org that updates on
an interval.

Args:

- `npmPackageOrOrg`: npmPackageOrOrg object returned from the `getNpmPackage` or `getNpmOrg` query
- `options`: optional options object
  - `intervalMs`: override the calculated interval

Returns:

- `count`: regularly updated download count
- `intervalMs`: the interval at which the count is updated (useful for
  configuring client animations, such as a NumberFlow component)

```ts
import { useNpmDownloadCounter } from "@erquhart/convex-oss-stats/react";
import NumberFlow from '@number-flow/react'

const npmOrg = useQuery(api.stats.getNpmOrg, { org: "convex-dev" });

const { count, intervalMs } = useNpmDownloadCounter(npmOrg)

return (
  <NumberFlow
    transformTiming={{
      duration: intervalMs,
      easing: 'linear',
    }}
    value={count}
    trend={1}
    continuous
    willChange
  />
)
```

## Querying data from the backend

You can also query data from the backend using the `ossStats` object.
Note: the data will only be available for the owners and npm orgs you configured
and have synced.

```ts
// Within a Convex query, mutation, or action:
// All of the owners you configured when initializing the OssStats object
const githubOwners = await ossStats.getAllGithubOwners(ctx);
// A single owner
const githubOwner = await ossStats.getGithubOwner(ctx, "get-convex");
// All of the npm orgs you configured when initializing the OssStats object
const npmOrgs = await ossStats.getAllNpmOrgs(ctx);
// A single npm org
const npmOrg = await ossStats.getNpmOrg(ctx, "convex-dev");
// A single github repo
const githubRepo = await ossStats.getGithubRepo(ctx, "get-convex/convex-js");
// Combined stats for a list of github repos
const githubRepos = await ossStats.getGithubRepos(ctx, [
  "get-convex/convex-js",
  "get-convex/convex-helpers",
]);
// A single npm package
const npmPackage = await ossStats.getNpmPackage(ctx, "@convex-dev/convex-js");
// Combined stats for a list of npm packages
const npmPackages = await ossStats.getNpmPackages(ctx, [
  "@convex-dev/convex-js",
  "@convex-dev/convex-helpers",
]);
```

## Options and configuration

### Manually syncing data

If you don't want to use the webhook, you can use a cron job to sync data:

```ts
// In convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";

export const syncStars = internalAction(async (ctx) => {
  await ossStats.sync(ctx);
});

const crons = cronJobs();

crons.interval("syncStars", { minutes: 15 }, internal.stats.syncStars);

export default crons;
```

You could alternatively call this from the CLI or dashboard:

```sh
npx convex run crons:syncStars
```

Or call it via an http endpoint:

```ts
// In convex/http.ts
import { httpAction } from "./_generated/server";
//...
http.route({
  path: "/syncStars",
  method: "POST",
  handler: httpAction(async (ctx, request) => {
    if (request.headers.get("x-api-key") !== process.env.API_KEY) {
      return new Response("Unauthorized", { status: 401 });
    }
    await ossStats.sync(ctx);
    return new Response("ok", { status: 200 });
  }),
});
```

`API_KEY` can be set in the dashboard or via `npx convex env set API_KEY=...`

### Override the default `/events/github` path

```ts
ossStats.registerRoutes(http, {
  path: "/my/github/webhook",
});
```