GitHub README cards API

Small HTTP service that renders SVG cards for a GitHub profile README: stats, top languages, pinned repo, gists, and contribution streaks. It is written in TypeScript on Hono and is meant to be self-hosted (for example on Vercel).

Why this exists

The feature set and layout are inspired by the excellent community projects github-readme-stats (Node) and github-readme-streak-stats (PHP). This repository is not a fork of either one: it is a fresh implementation with only the cards and query options needed here, a single runtime (Hono + TS), and no copied source trees from those projects.

If you need every upstream feature, use the originals; if you want a compact, typed stack you control, use or fork this.

Endpoints

Path	Card
GET /api/stats	GitHub user stats (commits, PRs, stars, rank, etc.)
GET /api/top-langs	Most-used languages
GET /api/pin	Single pinned repository
GET /api/gist	Gist summary
GET /api/streak	Contribution streak (daily or weekly mode)
GET /api/status/up	Health check (GitHub API reachable)
GET /api/status/pat	Validates GITHUB_TOKEN against the API

GET / lists these routes as plain text.

Responses are image/svg+xml with cache headers appropriate per card.

Quick start

Requirements: Node 20+ (or Bun), a GitHub personal access token with scopes sufficient for the data you request (public data usually needs minimal read scopes).

pnpm install
cp .env.example .env   # set GITHUB_TOKEN (required)
pnpm dev

Open http://localhost:3000 (see src/index.ts for the default port).

Production build:

pnpm run build
pnpm start

The repo includes vercel.json with a frozen install command for deployment; point the Vercel project at this app’s fetch handler per your hosting setup.

Environment variables

Variable	Required	Description
GITHUB_TOKEN	Yes	Token used for GitHub GraphQL/REST calls.
DEBUG	No	Set to true for extra logging (e.g. rank breakdown). Default false.
WHITELIST	No	If non-empty, only these comma-separated GitHub usernames (or gist IDs for gist routes) may request cards—useful on a shared deployment.
BLACKLIST	No	Comma-separated usernames blocked when WHITELIST is not used.

Using cards in your README

Replace YOUR_HOST and USERNAME with your deployment URL and GitHub login.

Stats (github-readme-stats-style query params):

![GitHub stats](https://YOUR_HOST/api/stats?username=USERNAME&theme=dark&hide_border=true&show_icons=true)

Top languages:

![Top languages](https://YOUR_HOST/api/top-langs?username=USERNAME&theme=dark&layout=compact)

Streak (supports mode=weekly, user= as alias for username, and other options aligned with streak-stats):

![Streak](https://YOUR_HOST/api/streak?username=USERNAME&theme=dark&mode=weekly)

Themes: built-in theme names work via ?theme=... on all cards. See docs/themes.md.

i18n: locale query parameter where supported (e.g. en, de, pl, uk-ua—see src/i18n/locales).

Project layout

• src/index.ts — Hono app and route mounting
• src/routes/ — HTTP handlers and query parsing
• src/cards/ — SVG renderers
• src/github/ — GitHub API clients and queries
• src/themes/ — Theme tokens
• docs/ — Environment notes and theme gallery

License

No LICENSE file is committed in this repo yet. Add one before publishing if you want a standard OSS license; respect the licenses of upstream inspirations when reusing ideas or assets.

Acknowledgements

• anuraghazra/github-readme-stats — stats and language cards popularized this pattern.
• DenverCoder1/github-readme-streak-stats — streak visualization and contribution semantics.

Thank you to the maintainers and contributors of those projects.