GitHub contribution streaks are a quick, visual way to show your coding activity and consistency. Instead of static badges, this PHP-based project dynamically generates customizable SVG images that display your total contributions, current streak, and longest streak on your GitHub profile README. Under the hood, it integrates directly with the GitHub API to fetch live user data and renders it into clean, themeable graphics. This approach gives you a personalized, always up-to-date snapshot of your GitHub streaks, which is both practical and visually appealing.
how github-readme-streak-stats generates streak visuals
At its core, this project is a PHP web service that queries GitHub’s API for a user’s contribution data and then dynamically generates SVG images representing streak statistics. The generated images can be embedded in Markdown, typically in GitHub profile READMEs, to display live streak data.
The architecture is straightforward: a PHP backend handles HTTP requests, uses the GitHub API to gather contribution counts and streak info, then builds an SVG on the fly. This SVG is returned as an image URL, meaning no client-side JavaScript is needed to render the streak stats. This server-side rendering approach ensures the images are always current whenever the README is loaded.
The repo supports multiple output formats: SVG is the primary, but PNG and JSON outputs are also available. PNG support is implemented using Inkscape within a Docker setup, which converts SVGs for environments that don’t support SVG rendering.
Customizability is a major feature. Users can adjust colors, themes, locale, and which stats to show by tweaking URL parameters. This flexibility allows the widget to blend seamlessly with any profile style or language preference.
what makes this streak stats project stand out technically
The standout aspect is the elegant use of server-side SVG generation to produce fully dynamic, customizable images without client-side dependencies. Many similar tools rely on static badges or client-side scripts, but this repo offers a lightweight, user-friendly way to display live data.
The PHP codebase is surprisingly clean and modular for a project serving dynamic images. It uses a simple routing approach and clear separation between data fetching, SVG rendering, and HTTP response handling. This makes it easier to understand and extend.
Supporting multiple locales and output formats adds complexity, but the repo handles it gracefully. The Docker deployment encapsulates dependencies like Inkscape for SVG-to-PNG conversion, isolating environment-specific details away from the main code.
The tradeoff is that running a dynamic web service in PHP means you need a hosting setup or container environment. While the repo provides a convenient public demo, self-hosting is recommended for reliability and privacy. This means extra operational overhead compared to static badges, but also more control.
Overall, the implementation strikes a good balance between simplicity and functionality, making it accessible while still powerful.
quick start with github-readme-streak-stats
Getting started is straightforward, especially if you just want to embed the default streak stats on your profile. The README provides this quick setup:
[](https://git.io/streak-stats)
Simply replace the user parameter with your GitHub username in the URL, then paste that markdown snippet into your GitHub profile README. This displays your live streak stats using the public demo instance.
For more control or privacy, you can self-host the service. The repo offers detailed Docker deployment instructions:
git clone https://github.com/DenverCoder1/github-readme-streak-stats.git
cd github-readme-streak-stats
Generate a GitHub Personal Access Token (no scopes required) from GitHub settings, then build and run the Docker container with your token:
docker build -t streak-stats .
docker run -d -p 8080:80 -e TOKEN=your_github_token_here streak-stats
Optionally, you can whitelist specific GitHub usernames for access via the WHITELIST environment variable.
This Docker setup supports all features, including PNG rendering, and lets you run the service in a controlled environment.
verdict: a practical tool for GitHub users who value live streak stats
GitHub-readme-streak-stats fills a niche by offering a dynamic, customizable way to display your GitHub contribution streaks with minimal fuss. Its PHP backend and SVG generation are cleanly implemented, and the Docker-based self-hosting option gives you control over reliability and data privacy.
The main limitation is the hosting requirement. If you want a zero-maintenance badge, static options might be easier. But if you want live, themeable streak stats that update automatically and can be self-hosted, this repo delivers effectively.
For developers who maintain public GitHub profiles regularly and want to showcase activity visually without relying on third parties, this project is a solid choice. The code is accessible enough to extend or tweak if needed, and the customization options make it versatile across different profile styles.
Related Articles
- Hatchet: durable background task orchestration with Go and Postgres — Hatchet offers a durable, fault-tolerant background task and workflow engine built with Go and Postgres. It supports com
- OpenAI Codex CLI: local-first AI coding assistant with ChatGPT integration — OpenAI Codex CLI brings AI coding assistance local to your terminal, integrating with ChatGPT plans for powerful hybrid
→ GitHub Repo: DenverCoder1/github-readme-streak-stats ⭐ 6,768 · PHP