repocard

Generate beautiful GitHub repository cards as PNG images — with commit activity heatmap, sparkline trend, language breakdown, stacked contributor avatars, latest release, and more.

Features

• macOS-style window chrome with URL bar
• Commit activity heatmap (last 26 weeks) with month & day labels
• Sparkline area chart showing commit trend
• Commit streak badge (consecutive active weeks)
• Peak commit week badge
• Language badge next to repo name
• Language breakdown bar with percentages
• Stacked contributor avatars + total contributor count
• Latest release tag with publish date
• README excerpt from the target repo
• Stats: stars, forks, open issues, watchers
• SVG icons throughout (no emoji font needed)
• Footer: created date, total commits, default branch, repo size
• Owner avatar with language-colored glow ring
• Subtle radial glow background per language color
• Top & bottom accent bars in language color
• 3 themes: dark, light, minimal
• PNG or WebP output

Install

npm install

Setup (optional)

Create a .env file to avoid hitting the 60 req/hr unauthenticated rate limit:

GITHUB_TOKEN=ghp_xxxxxxxxxxxxx

---

Web interface

Start the web server and open in browser:

npm run web
# → http://localhost:3000

Terminal-style UI — type a repo name or full GitHub URL, press Enter, the card appears instantly with download buttons. Theme and format can be selected from the page.

---

CLI

node index.js <owner/repo> [options]
node index.js <repos.txt> [options]

Options

Flag	Default	Description
--theme	dark	dark | light | minimal
--format	png	png | webp
--out	./output	Output folder
--name	repo name	Output filename (single repo only)
--token	$GITHUB_TOKEN	GitHub personal access token

Examples

# single repo
node index.js vercel/next.js

# with options
node index.js rust-lang/rust --theme=light --format=webp

# custom output path and filename
node index.js torvalds/linux --out=./cards --name=linux

# batch — one repo per line, # for comments
node index.js repos.txt --theme=dark

# pass token directly
node index.js owner/repo --token=ghp_xxx

Batch file format

# repos.txt
vercel/next.js
rust-lang/rust
microsoft/TypeScript

---

Rate limits

	Requests/hour
Without token	60
With token	5,000

Each card fetch uses 6 API requests (repo, languages, commit activity, contributors, readme, latest release).

Output

1200 × 630 px — standard Open Graph image size, ready for social sharing.

CLI saves to output/<repo>-card.png (or .webp) by default.

How it works

1. Fetches repo data from 6 GitHub REST API endpoints in parallel
2. Encodes owner and contributor avatars as base64 for offline rendering
3. Strips markdown/HTML from README to extract clean excerpt
4. Renders the card with Satori (HTML/CSS → SVG)
5. Converts SVG to PNG or WebP via Sharp
6. Caches the full API response for 1 hour in cache/

Stack

Package	Purpose
satori	HTML/CSS → SVG renderer
sharp	SVG → PNG/WebP conversion
express	Web server
@fontsource/inter	Inter font (local, no network)

Project structure

repocard/
├── server.js     # Web server (Express)
├── index.js      # CLI entry, batch mode
├── fetch.js      # GitHub API + cache layer
├── card.js       # Satori card template + themes
├── cache.js      # JSON cache with 1hr TTL
├── public/
│   └── index.html  # Terminal-style web UI
├── repos.txt     # Example batch file
└── output/       # Generated images (git-ignored)