📊 GitHubStats

Showcase and share your GitHub story — as beautiful, downloadable images.

Enter any GitHub username to reveal contributions, account age, active days, streaks, top languages and more. Every card can be shared or exported as an image.

Live demo · Report a bug · Request a feature

---

Table of contents

• Features
• Screenshots
• How it works
• Tech stack
• Getting started
• Configuration
• Deploy
• API
• Project structure
• Roadmap
• Contributing
• License
• Acknowledgements

Features

• 🟩 Contribution graph — full account history, GitHub-style heatmap with a year selector dropdown
• 📊 Contribution breakdown — view your activity year / month / week / day wise with a toggle
• 🏆 Top repositories — your top 5 repos ranked by commits (all-time with a token, recent activity otherwise)
• 🔢 Total contributions across commits, PRs, issues & reviews
• 📅 Account age — years and exact days since the account was created
• 🔥 Active days — how many days actually had contributions (the "green" days), shown as a percentage
• ⚡ Streaks — longest and current streak, plus your busiest day ever
• 👥 Followers, repos & total stars earned across public repositories
• 🧩 Top languages with the official GitHub color palette and a proportional bar
• 🖼️ Share any card as an image — native share sheet on supported devices, crisp 2× PNG download everywhere else
• 🌙 GitHub dark theme UI, fully responsive
• 🔓 No login, no database — works with zero secrets

Screenshots

Add screenshots or a GIF here once deployed.

docs/screenshot-dashboard.png
docs/screenshot-card.png

How it works

• Profile, repos & languages come from the public GitHub REST API.
• Contribution calendar comes from the free github-contributions-api (no auth required, full history).
• Card → image conversion happens entirely client-side with html-to-image.

The data is fetched server-side in a Next.js Route Handler and cached at the edge, so repeat lookups are fast and rate-limit friendly.

Tech stack

Layer	Choice
Framework	Next.js 15 (App Router)
UI	React 19, TypeScript, plain CSS (GitHub dark)
Data	GitHub REST API + github-contributions-api
Image export	html-to-image
Hosting	Vercel

Getting started

Prerequisites

• Node.js 18.18 or newer
• npm (ships with Node)

Installation

# 1. Clone
git clone https://github.com/PATILYASHH/githubstats.git
cd githubstats

# 2. Install dependencies
npm install

# 3. Start the dev server
npm run dev

Open http://localhost:3000 and enter a username.

Scripts

Command	Description
npm run dev	Start the development server
npm run build	Create a production build
npm start	Run the production build
npm run lint	Lint the codebase

Configuration

The app works with no environment variables. The only optional setting raises GitHub's unauthenticated rate limit (~60 requests/hour per IP):

Variable	Required	Description
GITHUB_TOKEN	No	A GitHub token (no scopes needed) to raise the API rate limit.

Create a .env.local file for local development:

GITHUB_TOKEN=ghp_your_personal_access_token

A classic token with no scopes (public data only) is enough.

Deploy

This is a standard Next.js App Router project. Deploy to Vercel in a few clicks:

1. Push your fork to GitHub.
2. Import the repository at vercel.com/new.
3. (Optional) add GITHUB_TOKEN under Project → Settings → Environment Variables.
4. Deploy. 🎉

API

A single JSON endpoint powers the dashboard.

GET /api/stats?username=<github-username>

Example

curl "https://githubstatss.vercel.app/api/stats?username=torvalds"

Response (truncated)

{
  "user": { "login": "torvalds", "name": "Linus Torvalds", "createdAt": "2011-09-03T..." },
  "contributions": {
    "total": 37404,
    "activeDays": 5109,
    "trackedDays": 5844,
    "accountAgeDays": 5407,
    "longestStreak": 98,
    "currentStreak": 0,
    "days": [{ "date": "2011-09-03", "count": 0, "level": 0 }]
  },
  "languages": [{ "name": "C", "count": 8, "percentage": 88.9, "color": "#555555" }],
  "totalStars": 248732
}

Errors return { "error": "message" } with an appropriate status (400, 404, 403, 500).

Project structure

githubstats/
├── app/
│   ├── api/stats/route.ts     # JSON endpoint (server-side GitHub fetch)
│   ├── globals.css            # GitHub dark theme styles
│   ├── layout.tsx             # Root layout + metadata
│   └── page.tsx               # Home page + dashboard
├── components/
│   ├── ContributionGraph.tsx  # Heatmap + year selector
│   ├── ShareCard.tsx          # Card wrapper + share-as-image
│   └── icons.tsx              # Inline SVG icons
├── lib/
│   ├── colors.ts              # Language & heatmap color palettes
│   ├── github.ts              # Data fetching & aggregation
│   └── types.ts               # Shared TypeScript types
└── ...

Roadmap

• Light theme toggle
• Per-card theme/color customization
• Compare two users side by side
• OG image generation for shared profile links
• More cards (top repos, commit-time heatmap)

See open issues for the full list.

Contributing

Contributions are what make open source great. Please read CONTRIBUTING.md and our Code of Conduct before opening a PR.

1. Fork the project
2. Create your branch (git checkout -b feature/amazing-card)
3. Commit your changes (git commit -m 'Add amazing card')
4. Push (git push origin feature/amazing-card)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for details.

Acknowledgements

• github-contributions-api — contribution calendar data
• html-to-image — DOM-to-PNG export
• GitHub Linguist — language color palette
• Next.js & Vercel

---

Built with ❤️ by Yash Patil · githubstatss.vercel.app