@erquhart/convex-oss-stats
v0.3.2
Published
A Convex Component for syncing and rendering open source project data.
Downloads
558
Readme
Convex OSS Stats Component
Note: Convex Components are currently in beta.
Keep GitHub and npm data for your open source projects synced to your Convex database.
// convex/stats.ts
import { OssStats } from '@convex-dev/oss-stats'
import { components } from './_generated/api'
const ossStats = new OssStats(components.ossStats, {
githubOwners: ['get-convex'],
npmOrgs: ['convex-dev'],
})
export const { getGithubOwner } = ossStats.api()
// src/OssStats.tsx
import { useQuery } from 'convex/react'
import { api } from '../convex/_generated/api'
const OssStats = () => {
const github = useQuery(api.stats.getGithubOwner, {
owner: 'get-convex',
})
const npm = useQuery(api.stats.getNpmOrg, {
org: 'convex-dev',
})
return (
<>
{/* If webhook is registered, this will update in realtime 🔥 */}
<div>{github.starCount}</div>
<div>{npm.downloadCount}</div>
</>
)
}
Prerequisites
GitHub Account (if syncing GitHub data)
Create a GitHub account and get the following credentials:
- Access Token
- Go to your GitHub account settings and generate a new access token - just needs read access to public repositories.
- Webhook Secret
- Note: this is optional, you'll walk through these steps for every org or repo that you want to get live star counts for
- Go to the settings for the org/repo and create a new webhook
- Get the HTTP Actions URL from your production Convex deployment: https://dashboard.convex.dev > Production project deployment > Settings > URL & Deploy Key > 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.
Convex App
You'll need a Convex App to use the component. Follow any of the Convex quickstarts to set one up.
Installation
Install the component package:
npm install @convex-dev/oss-stats
Create a convex.config.ts
file in your app's convex/
folder and install the component by calling use
:
// convex/convex.config.ts
import { defineApp } from "convex/server";
import ossStats from "@convex-dev/oss-stats/convex.config";
const app = defineApp();
app.use(ossStats);
export default app;
Set your API credentials:
npx convex env set GITHUB_ACCESS_TOKEN=xxxxx
npx convex env set GITHUB_WEBHOOK_SECRET=xxxxx
Instantiate an OssStats Component client in a file in your app's convex/
folder:
// convex/example.ts
import { OssStats } from "@convex-dev/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:
// http.ts
import { ossStats } from "./example";
import { httpRouter } from "convex/server";
const http = httpRouter();
// this call registers the routes necessary for the component
ossStats.registerRoutes(http, {
// Optionally override the default path that GitHub events will be sent to
// (default is /events/github)
path: "/events/github",
});
export default http;
Querying data
To get data for a GitHub owner (org or user), use the getGithubOwner
query:
// src/OssStats.tsx
import { useQuery } from 'convex/react'
import { api } from '../convex/_generated/api'
const OssStats = () => {
const github = useQuery(api.stats.getGithubOwner, {
owner: 'get-convex',
})
const npm = useQuery(api.stats.getNpmOrg, {
org: 'convex-dev',
})
return (
<>
{/* If webhook is registered, this will update in realtime 🔥 */}
<div>{github.starCount}</div>
<div>{npm.downloadCount}</div>
</>
)
}