⚡ Awesome GitHub Stats

Embeddable SVG cards for GitHub READMEs that track your life outside code.

Gym streaks, gaming hours, reading progress, and what you're currently learning — in the same clean, auto-updating visual language devs already trust from github-readme-stats.

---

Why?

Every GitHub profile widget measures coding activity — commits, PRs, languages, streaks. None of them touch anything outside the git graph.

Awesome GitHub Stats sits next to your coding stats, not instead of them. One embed, one URL, one card.

---

Quick Start

1. Pick a card

Card	Endpoint	What it shows
🔥 Gym Streak	/api/card/gym	Current streak, longest streak, weekly dots
🎮 Gaming Stats	/api/card/gaming	Total hours, current game, top games chart
📚 Reading Progress	/api/card/reading	Books read vs goal, current book, anime
🧠 Currently Learning	/api/card/learning	Topics with progress bars, streak days

2. Add your data

Create a life-stats.json in your repo (see examples/life-stats.example.json):

{
  "username": "your-github-username",
  "cards": [
    {
      "type": "gym",
      "currentStreak": 14,
      "longestStreak": 45,
      "totalWorkouts": 312,
      "weeklyGoal": 5,
      "weeklyProgress": [true, true, false, true, true, false, false]
    }
  ]
}

3. Embed in your README

![Gym Streak](https://your-app.vercel.app/api/card/gym?data=YOUR_BASE64_DATA)

The data parameter is your card data, base64-encoded. Use the generator page to build your URL.

---

Themes

Five polished themes ship at launch:

Theme	Look
default	Light paper, cobalt accent
dark	GitHub dark mode
cobalt	Cool-white, electric blue
terminal	Black + phosphor green
warm	Cream paper, terracotta accent

Add ?theme=dark to any card URL:

![Gaming Stats](https://your-app.vercel.app/api/card/gaming?theme=dark)

---

Steam Integration

Set your Steam ID in the gaming card data to auto-populate hours and top games from the Steam Web API (free key).

1. Get a Steam Web API Key (free)
2. Set STEAM_API_KEY as an environment variable on your Vercel deployment
3. Add your steamId to the gaming card in life-stats.json

---

API Reference

GET /api/card/[type]

Param	Type	Required	Description
type	gym | gaming | reading | learning	✅	Card type (path param)
theme	default | dark | cobalt | terminal | warm	❌	Visual theme (default: default)
data	string	❌	Base64-encoded JSON card data. Omit for demo preview.

Response: image/svg+xml with Cache-Control: public, s-maxage=3600

---

GitHub Action

Automate daily updates by adding the example workflow to your repo:

# .github/workflows/update-life-stats.yml
name: Update Life Stats
on:
  schedule:
    - cron: '0 6 * * *'

---

Tech Stack

• Next.js 15 (App Router) — API routes + React frontend
• Server-rendered SVGs — pure SVG 1.1, no JS, GitHub Camo-safe
• Vercel (free tier) — edge caching, 100K invocations/month
• Zod — runtime data validation
• Steam Web API — free gaming data integration

---

🚀 Deployment (Vercel)

The easiest way to deploy this project for free is using Vercel. Vercel provides a free Hobby tier with unlimited API requests, making it perfect for hosting these dynamic SVGs.

1-Click Deploy

Manual Deploy (Vercel CLI)

1. Install the CLI: npm i -g vercel
2. Run vercel in your terminal
3. Follow the prompts to deploy. Your generator will instantly be live at your new .vercel.app domain!

Once deployed, visit your Vercel URL to access the interactive Configurator. You can type in your stats, pick your theme, and simply copy-paste the generated Markdown into your GitHub README.

---

Development

npm install
npm run dev
# Open http://localhost:3000

The card API runs at http://localhost:3000/api/card/[type].

---

License

MIT