# @erquhart/convex-oss-stats 中文文档

规范地址：https://npmcn.com/package/%40erquhart/convex-oss-stats/

版本：0\.8\.2
npm 元数据更新时间：2025-11-29T04:29:57.909Z
中文译文更新时间：2026-11-13T21:31:29.923Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40erquhart/convex-oss-stats
原文对照：https://npmcn.com/package/%40erquhart/convex-oss-stats/?lang=original
项目主页：https://github.com/erquhart/convex-oss-stats#readme
源码仓库：https://github.com/erquhart/convex-oss-stats

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：218 kB，64 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：11 个
- peer 依赖：convex ^1\.29\.0，react ^18 \|\| ^19，react-dom ^18 \|\| ^19
- 首次发布：2024-11-24T18:21:59.381Z
- 最新版本发布：2025-11-29T04:29:57.727Z
- 近 30 天下载量：3674（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 2 个）

## 中文简介

用于同步和渲染开源项目数据的 Convex 组件 .

## 安装

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

也可以使用：`pnpm add @erquhart/convex-oss-stats`、`yarn add @erquhart/convex-oss-stats`、`bun add @erquhart/convex-oss-stats`

## README

# Convex OSS 数据组件

[![npm version](https://badge.fury.io/js/@erquhart%2Fconvex-oss-stats.svg)](https://badge.fury.io/js/@erquhart%2Fconvex-oss-stats)

为您的开源项目保持 GitHub 和 npm 数据同步到您的 Convex 数据库 .

```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>
    </>
  );
};
```

## 先决条件

### Convex 应用程序

你需要一个Convex App来使用组件. 跟着任何 [Convex 快速启动](https://docs.convex.dev/home) 来设置一个.

### GitHub 账户( 如果同步 GitHub 数据)

从您的 GitHub 账户获取以下证书:

-   **访问托肯**
    -   转到账户设置并生成新访问令牌, 并读取访问到 公共仓库.
-   **Webhook 密钥**: 为每个 org 或 repo 做此操作 .
    -   注:这是可选的。 没有它,你就不会得到 活星数. 看怎么样 [手动同步数据](https://npmcn.com/package/%40erquhart/convex-oss-stats/#readme-manually-syncing-data)。 。 。 .
    -   转到 Org/repo 的设置中并创建新的 webhook .
    -   为您获取 HTTP 动作 URL **生产** 对流部署设置 : [https://dashboard.convex.dev/部署/设置](https://dashboard.convex.dev/deployment/settings) > HTTP 动作 URL
    -   有效载荷 URL : `<http-actions-url>/events/github`
    -   内容类型 : `application/json`
    -   在您的 Convex 部署和 GitHub 之间创建共享密钥
    -   哪些事件? > 选择个人 > 仅限恒星

### Npm 数据说明

此组件访问 npm 数据是公开的,不需要任何证书.

## 安装

安装组件包 :

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

创建一个 `convex.config.ts` 应用程序中的文件 `convex/` 通过调用文件夹并安装组件 `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;
```

设置您的 API 证书 :

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

如果你没有跑 `npx convex dev` 不过,你需要现在就开始. 它会生成您的组件的代码 `convex/_generated/api` 文件夹, ,并将在您更改文件时自动部署更改 `convex/`。 。 。 .

将 OssStats 组件客户端在您的应用程序中的文件进行校正 `convex/` 文件夹 :

```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();
```

通过创建一个 `http.ts` 文档中 `convex/` 文件夹并使用您导出于上面的客户端 :

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

const http = httpRouter();

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

## 从前端查询数据

使用 `useQuery` 钩从组件中获取数据。 以下是如何获取 GitHub 拥有者( org 或用户) 和 npm 包或 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>
    </>
  )
}
```

### 可用查询

#### `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"] }
);
```

### 反应钩

#### `useNpmDownloadCounter`

提供 npm 软件包或 org 更新的预测下载数 一个间隔.

参数 :

-   `npmPackageOrOrg`: npmPackageOrg 对象从 `getNpmPackage` 或者说 `getNpmOrg` 查询
-   `options`: 可选选项对象
    -   `intervalMs`: 覆盖计算间隔

回返情况:

-   `count`: 定期更新的下载数
-   `intervalMs`: 更新计数的间隔(用于 配置客户端动画, 如数字花组件)

```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
  />
)
```

## 查询后端的数据

您也可以使用 `ossStats` 对象. 注意: 数据只提供给您配置的拥有者和 npm orgs 并同步了.

```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",
]);
```

## 选项和配置

### 手动同步数据

如果您不想使用 Webhook, 您可以使用 cron 任务来同步数据 :

```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;
```

你可以从CLI或仪表板上调用这个:

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

或者通过一个http端点来称呼它:

```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` 可在仪表板上设置或通过 `npx convex env set API_KEY=...`

### 覆盖默认值 `/events/github` 路径

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

## 常见问题

### @erquhart/convex-oss-stats 是什么？

用于同步和渲染开源项目数据的 Convex 组件 \.

### 如何安装 @erquhart/convex-oss-stats？

在项目目录运行 npm install @erquhart/convex-oss-stats，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：convex（^1\.29\.0）、react（^18 \|\| ^19）、react-dom（^18 \|\| ^19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @erquhart/convex-oss-stats 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @erquhart/convex-oss-stats 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @erquhart/convex-oss-stats 可以商用吗？

@erquhart/convex-oss-stats 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @erquhart/convex-oss-stats 的下载量有多少？

根据 npm 官方下载统计，@erquhart/convex-oss-stats 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,674 次，日均约 122 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @erquhart/convex-oss-stats 还在维护吗？

最新版本 0\.8\.2 发布于 2025/11/29（11 个月前）；至今共发布 35 个版本，其中过去 12 个月发布了 2 个；首次发布于 2024/11/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。