GitHub profiles often benefit from displaying contribution statistics, but static badges fall short of showing a nuanced picture. The github-readme-stats project fills this gap by generating dynamic SVG cards that visualize GitHub user data with customizable themes and a unique percentile-based ranking system. This repo showcases a practical serverless approach to integrating with the GitHub API while tackling rate limits and delivering a developer-friendly customization experience.
what github-readme-stats does and how it works
github-readme-stats is a JavaScript-based serverless service that dynamically generates SVG images showing GitHub user statistics. These SVG cards are designed to be embedded in GitHub README files, providing a live snapshot of a user’s contributions, repositories, and other metrics.
Under the hood, the service runs on Vercel, a popular serverless deployment platform. It queries the GitHub REST API to fetch user data, then renders this data into SVG format dynamically for each request. The stack is centered around JavaScript/Node.js, leveraging serverless functions to keep overhead minimal and scaling seamless.
Customization is a core feature: users can control themes, colors, locales, and which stats to show or hide by tweaking URL parameters. This level of flexibility means the cards can blend seamlessly into any profile style or language preference.
The project implements a caching layer with time-to-live (TTL) values between 21,600 and 86,400 seconds (6 to 24 hours). This caching is crucial because GitHub enforces an API rate limit of 5,000 requests per hour. By caching responses, the service mitigates hitting this limit, improving reliability and reducing latency.
technical strengths and architectural tradeoffs
The standout technical feature is the integration of a statistical ranking algorithm found in src/calculateRank.js. Instead of simply showing raw counts, the project calculates percentile-based ranks for various contribution metrics using weighted sums of percentiles derived from exponential and log-normal cumulative distribution functions. These ranks are then mapped to grades from S (top 1%) through C, gamifying contributions in a meaningful way.
This ranking system isn’t just visual flair; it provides context to raw numbers, helping users understand their standing relative to a broader population. The use of actual statistical distributions is a thoughtful design choice that lends rigor and fairness to the ranks.
The caching strategy is another technical highlight. The TTL range balances freshness with API rate limit constraints. The cache duration is long enough to reduce redundant API calls but short enough to keep stats reasonably up-to-date. This tradeoff is fundamental in any system relying on rate-limited external APIs. While it means some data might be stale for hours, it avoids downtime or errors caused by hitting the rate limit.
Deployment on Vercel streamlines scaling and reduces infrastructure management effort. However, relying on a third-party platform introduces dependency on Vercel’s uptime and limits. For users needing private stats or higher request volumes, the project supports self-hosting with a GitHub Personal Access Token (PAT), allowing more control over API quotas and cache management.
The codebase itself is surprisingly clean and well-structured for a project of its scope. URL parameter parsing, theme management, API calls, and SVG rendering are neatly separated, making it easier to follow and extend.
self-hosting and quickstart instructions
Running your own instance of github-readme-stats lets you avoid the public API rate limits and gain full control over caching, tokens, and private stats display.
First step: get your Personal Access Token (PAT)
For deploying your own instance, you’ll need a GitHub PAT. The repo details two methods to generate one — classic tokens and fine-grained tokens — each with specific scopes.
Classic token
- Go to Account -> Settings -> Developer Settings -> Personal access tokens -> Tokens (classic).
- Click on
Generate new token -> Generate new token (classic). - Scopes to select:
- repo
- read:user
- Click on
Generate tokenand copy it.
Fine-grained token
[!WARNING] This limits the scope to issues in your repositories and includes only public commits.
- Go to Account -> Settings -> Developer Settings -> Personal access tokens -> Fine-grained tokens.
- Click on
Generate new token -> Generate new token. - Select an expiration date
- Select
All repositories - Scopes to select in
Repository permission:- Commit statuses: read-only
- Contents: read-only
- Issues: read-only
- Metadata: read-only
- Pull requests: read-only
- Click on
Generate tokenand copy it.
On Vercel
You can deploy your own instance easily on Vercel. This eliminates concerns about the 5,000 requests per hour public API limit since your instance will use your PAT and cache settings.
A deploy button is provided in the repo’s README to get started quickly.
[!NOTE] Since version #58, the project can handle more than 5k requests and has fewer downtime issues.
who should consider github-readme-stats
This project is well-suited for developers who want to showcase their GitHub stats dynamically in README profiles with a visually appealing and customizable design. The percentile-based ranking adds a layer of context that raw numbers alone don’t provide.
If you’re concerned about API rate limits or want to include private repositories and contributions, self-hosting is the way to go. The setup requires a GitHub PAT and some familiarity with Vercel or serverless deployments.
The tradeoff to keep in mind is caching: stats may be up to a day old depending on cache TTL, which is a necessary compromise to avoid exhausting API quotas. Also, the service depends heavily on GitHub’s API availability and response times.
Overall, github-readme-stats is a practical, well-engineered tool that solves a real problem for developers wanting to represent their GitHub activity in a personalized, data-driven way. The ranking algorithm is a solid example of applying statistical methods in a developer tool context, a detail worth understanding even if you don’t adopt the project directly.
Related Articles
- Generating dynamic GitHub contribution streak stats as SVG images — This PHP project generates customizable SVG images displaying GitHub contribution streaks for profile READMEs, with self
- Maigret: A resilient OSINT username scraper across thousands of sites — Maigret is a Python-based OSINT tool that scrapes public profiles by username from 3,000+ sites without API keys. It fea
- HelloGitHub: How curated open source content drives community engagement at scale — HelloGitHub curates entry-level open source projects monthly, fostering community engagement through human curation rath
→ GitHub Repo: anuraghazra/github-readme-stats ⭐ 79,246 · JavaScript