GitHub Readme Stats

Dynamically generated GitHub stats cards for your README.

English · 繁體中文

Table of contents

• Quick Start
• User Cards
  • GitHub Stats Card
  • Top Languages Card
  • Streak Card
  • Heatmap Card
  • WakaTime Card
• Repository Cards
  • Repository Card
  • Sparkline Card
• Gist Card
• Deployment
• Configuration
• API Documentation
• Support
• Contributing
• Important Notes

Quick Start

1. Deploy your instance — follow Deployment until you have a working Workers URL. Verify in a browser:

https://YOUR-INSTANCE.WORKERS.DEV/api?username=YOUR_USERNAME 2. Add this to your README (replace placeholders with your Workers hostname and GitHub username):

![GitHub Stats](https://YOUR-INSTANCE.WORKERS.DEV/api?username=YOUR_USERNAME)

User Cards

Cards keyed by GitHub username.

GitHub Stats Card

Display your GitHub statistics including stars, commits, pull requests, and more.

Basic Usage

![GitHub Stats](https://YOUR-INSTANCE.WORKERS.DEV/api?username=YOUR_USERNAME)

Examples

Use a theme:

![GitHub Stats](https://YOUR-INSTANCE.WORKERS.DEV/api?username=YOUR_USERNAME&theme=radical)

Custom colors:

![GitHub Stats](https://YOUR-INSTANCE.WORKERS.DEV/api?username=YOUR_USERNAME&bg_color=151515&title_color=fff&text_color=9f9f9f)

Responsive Themes

Use GitHub's theme context tags for automatic dark/light mode:

[![GitHub Stats Dark](https://YOUR-INSTANCE.WORKERS.DEV/api?username=YOUR_USERNAME&theme=dark#gh-dark-mode-only)](https://github.com/YOUR_USERNAME)
[![GitHub Stats Light](https://YOUR-INSTANCE.WORKERS.DEV/api?username=YOUR_USERNAME&theme=default#gh-light-mode-only)](https://github.com/YOUR_USERNAME)

See all available themes. All options: API.md — Stats Card.

Top Languages Card

Display your most frequently used programming languages.

Basic Usage

![Top Languages](https://YOUR-INSTANCE.WORKERS.DEV/api/top-langs?username=YOUR_USERNAME)

Examples

Compact layout:

![Top Languages](https://YOUR-INSTANCE.WORKERS.DEV/api/top-langs?username=YOUR_USERNAME&layout=compact)

Donut chart:

![Top Languages](https://YOUR-INSTANCE.WORKERS.DEV/api/top-langs?username=YOUR_USERNAME&layout=donut)

All options: API.md — Top Languages Card.

Streak Card

Display GitHub contribution streak statistics with current streak as the hero metric.

Basic Usage

![GitHub Streak](https://YOUR-INSTANCE.WORKERS.DEV/api/streak?username=YOUR_USERNAME)

Examples

Weekly streak mode:

![GitHub Streak](https://YOUR-INSTANCE.WORKERS.DEV/api/streak?username=YOUR_USERNAME&mode=weekly&theme=radical)

Hide longest streak:

![GitHub Streak](https://YOUR-INSTANCE.WORKERS.DEV/api/streak?username=YOUR_USERNAME&hide_longest=true)

All options: API.md — Streak Card.

Heatmap Card

Render a GitHub-style contribution heatmap grid.

Basic Usage

![Contribution Heatmap](https://YOUR-INSTANCE.WORKERS.DEV/api/heatmap?username=YOUR_USERNAME)

Example

Custom cell colors:

![Contribution Heatmap](https://YOUR-INSTANCE.WORKERS.DEV/api/heatmap?username=YOUR_USERNAME&heatmap_colors=161b22,0e4429,006d32,26a641,39d353)

All options: API.md — Heatmap Card.

WakaTime Card

Display your WakaTime coding statistics.

Warning

Your WakaTime profile must be public. Enable both "Display code time publicly" and "Display languages, editors, os, categories publicly" in your WakaTime settings.

Basic Usage

![WakaTime Stats](https://YOUR-INSTANCE.WORKERS.DEV/api/wakatime?username=YOUR_WAKATIME_USERNAME)

Example

![WakaTime Stats](https://YOUR-INSTANCE.WORKERS.DEV/api/wakatime?username=YOUR_WAKATIME_USERNAME&layout=compact)

All options: API.md — WakaTime Card.

Repository Cards

Cards keyed by repository owner and name (username + repo).

Repository Card

Pin additional repositories beyond GitHub's 6-repo limit.

Basic Usage

![Repository Card](https://YOUR-INSTANCE.WORKERS.DEV/api/pin?username=YOUR_USERNAME&repo=REPO_NAME)

Example

![Repository Card](https://YOUR-INSTANCE.WORKERS.DEV/api/pin?username=YOUR_USERNAME&repo=github-readme-stats&show_owner=true)

All options: API.md — Repository Card.

Sparkline Card

Render a cumulative commit history sparkline for one repository (like star history), using default-branch commits over the last N days (default 30).

Basic Usage

![Repo Commit Sparkline](https://YOUR-INSTANCE.WORKERS.DEV/api/sparkline?username=OWNER&repo=REPO_NAME)

Example

![Repo Commit Sparkline](https://YOUR-INSTANCE.WORKERS.DEV/api/sparkline?username=OWNER&repo=REPO_NAME&days=14&theme=radical)

All options: API.md — Sparkline Card.

Gist Card

Display GitHub Gists in your README.

Basic Usage

![Gist Card](https://YOUR-INSTANCE.WORKERS.DEV/api/gist?id=GIST_ID)

Example

![Gist Card](https://YOUR-INSTANCE.WORKERS.DEV/api/gist?id=bbfce31e0217a3689c8d961a356cb10d&show_owner=true)

All options: API.md — Gist Card.

Deployment

Prerequisites

1. Node.js 22+ (matches this repo's engines field)
2. GitHub Personal Access Token (PAT) — required. Set GITHUB_PAT as a Worker secret. Scope at GitHub token settings: public stats need read:user; private stats need repo + read:user (see Important Notes).

Deploy to Cloudflare Workers

1. Fork this repository
2. Install dependencies: pnpm install (install pnpm with npm install -g pnpm if needed)
3. Configure: node scripts/generate-wrangler-config.js — then pnpm wrangler secret put GITHUB_PAT for production
4. Deploy: pnpm run deploy — in Workers Builds, use pnpm run deploy (not bare wrangler). Set GITHUB_PAT; optional GitHub Actions secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
5. Use https://YOUR-INSTANCE.WORKERS.DEV in your README embed URLs

Environment Variables

Variable	Description
GITHUB_PAT	GitHub PAT (required); add GITHUB_PAT_2, … for more quota
WHITELIST	Comma-separated allowed usernames
CACHE_SECONDS	Default cache duration in seconds (0 disables)

Full list: API.md — Environment Variables.

Warning

Redeploy after changing environment variables.

Important

For internet-reachable instances, set WHITELIST to intended usernames. Unset WHITELIST lets any username consume your GitHub quota. If you expose /api/gist, set GIST_WHITELIST to allowed gist IDs.

Use Sync Fork to pull upstream changes; redeploy and re-check secrets after syncing.

Configuration

Aligning Cards Side by Side

[![YOUR_USERNAME's GitHub stats](https://YOUR-INSTANCE.WORKERS.DEV/api?username=YOUR_USERNAME)](https://github.com/YOUR_USERNAME)
[![YOUR_USERNAME's top languages](https://YOUR-INSTANCE.WORKERS.DEV/api/top-langs?username=YOUR_USERNAME&layout=compact)](https://github.com/YOUR_USERNAME)

Locales

Set locale= on any card URL (e.g. &locale=es). Supported codes: API.md — Supported Locales.

Caching

Each card type has default cache durations and per-card min/max clamps for cache_seconds; override globally with CACHE_SECONDS. Details: API.md — Cache Durations.

API Documentation

Full reference: API.md, hosted docs, or openapi.yaml.

Support

If something is not working:

• Confirm your Workers URL loads in a browser (see Quick Start)
• Check PAT scopes and private-stats caveats in Important Notes and Deployment
• For WakaTime cards, confirm profile visibility under WakaTime Card
• Open an issue with the failing URL (redact secrets)

When things go wrong

Card endpoints return error SVGs (not JSON) for most failures:

What you see	Likely cause
Missing username / parameter error	username (or repo, id) not in the URL
User not found	GitHub username typo or organization name used as username
Rate limit / downtime message	GitHub API quota exhausted — add GITHUB_PAT_2, tighten WHITELIST, or wait
No tokens / PAT message	GITHUB_PAT secret not set on the Worker
WakaTime user not found	WakaTime profile or visibility settings (see WakaTime Card)

Full error shapes: API.md — Error Handling.

Contributing

Contributions welcome — star the repo, open issues, or send PRs.

Important Notes

Important

This fork is self-host-only — deploy your own Cloudflare Workers instance; there is no shared public demo URL in this repo. The GitHub API allows 5k requests per hour per PAT. Caching reduces repeat GitHub API hits for the same card URL; it does not guarantee staying under the limit when many usernames are requested, caches expire, or CACHE_SECONDS is 0. Set WHITELIST to the usernames you intend to serve, and add GITHUB_PAT_2 (and further) tokens if you need more quota.

Warning

By default, cards only show statistics from public repositories. To include private repository statistics, deploy your own instance with a GitHub Personal Access Token that belongs to the same user as username. Private-repo aggregates rendered this way are still served on the public card URL — treat that as intentional disclosure, restrict the instance with WHITELIST, and do not embed the URL where those totals should stay private. Organization or SSO-restricted private repos may remain invisible even with a PAT.