GitHub Readme Stats — Dynamic Stats Cards for Your Profile

Introduction

GitHub Readme Stats renders live statistics about your GitHub activity as embeddable SVG cards. It pulls data from the GitHub GraphQL API and generates visually appealing widgets showing stars, commits, PRs, issues, and language breakdowns directly in any Markdown file.

What GitHub Readme Stats Does

• Generates real-time stats cards (total stars, commits, PRs, issues, contributions)
• Renders top-languages cards with multiple layout options (compact, donut, pie)
• Provides repository pin cards for showcasing specific projects
• Supports WakaTime integration for coding activity tracking
• Offers streak stats for contribution consistency visualization

Architecture Overview

The project runs as a Vercel serverless function. Each request hits a Node.js handler that authenticates with the GitHub GraphQL API using a personal access token, fetches user statistics, applies theme and layout parameters, then returns a dynamically rendered SVG image with appropriate cache headers.

Self-Hosting & Configuration

• Deploy to Vercel with one click using the provided deploy button
• Set GITHUB_TOKEN environment variable for API authentication
• Configure PAT_1 for higher rate limits on self-hosted instances
• Customize cache duration via the cache_seconds query parameter
• Support for multiple GitHub tokens via comma-separated PAT values

Key Features

• 30+ built-in themes (radical, merko, gruvbox, tokyonight, etc.)
• Fully customizable colors, borders, icons, and card dimensions
• Automatic language exclusion and card hiding options
• Internationalization with 40+ locale translations
• Responsive SVG output that works in any Markdown renderer

Comparison with Similar Tools

• GitHub Profile Trophy — focuses on achievement trophies rather than stats
• Metrics (lowlighter) — more comprehensive but heavier setup with GitHub Actions
• Socialify — project-level social cards, not user statistics
• Repobeats — analytics for individual repositories, not user profiles

FAQ

Q: Why does my stats card show incorrect commit counts? A: By default only public commits count. Add count_private=true parameter or enable private contributions in GitHub settings.

Q: Can I use this without deploying my own instance? A: Yes, the default Vercel deployment at github-readme-stats.vercel.app is free to use with query parameters.

Q: How do I hide specific languages from the top-langs card? A: Use the hide parameter: ?hide=html,css,jupyter%20notebook to exclude languages.

Q: What is the rate limit for the default instance? A: The shared instance handles thousands of requests per hour with aggressive SVG caching.

Sources

• https://github.com/anuraghazra/github-readme-stats
• https://github.com/anuraghazra/github-readme-stats#readme