🚀 GitHub Profile Stats API

Beautiful, fast, and cache-friendly SVG cards for your GitHub Profile README — including Top Languages, GitHub Overview (Commits/PRs/Issues), and customizable Skills. Built on GitHub GraphQL with smart caching for speed. ✨

🌟 Features

• 📊 GitHub Overview card: total commits, PRs, and issues.
• 🧠 Top Languages card: top 5 languages across public repos.
• 🧩 Skills card: gradient pills with optional icons.
• ♻️ Smart caching: 6-hour TTL via node-cache.
• ⚙️ Serverless-ready: Vercel configuration included.

🔧 Environment

Create a .env file (on local and in your hosting provider):

GITHUB_API_TOKEN=ghp_your_personal_access_token
GITHUB_USERNAME=your_default_github_username

Notes:

• GITHUB_API_TOKEN must be a GitHub Personal Access Token with access to the GraphQL API (no special scopes required for public data).
• GITHUB_USERNAME is used when username is not supplied in requests.

🧭 Public APIs

All endpoints are GET.

• GET /ping — Health check. Returns JSON { message: "pong" }.
• GET /error — Throws a test error (useful for verifying error handling).
• GET /languages?username=<name> — Returns SVG showing top languages.
• GET /stats?username=<name> — Returns SVG showing commits, PRs, and issues.
• GET /skills?skills=a,b,c — Returns SVG skills pills; supports many common tech names.

Content type for card endpoints: image/svg+xml. Health/error endpoints return JSON.

🔎 Query Parameters

• username (optional for /languages and /stats): defaults to GITHUB_USERNAME.
• skills (required for /skills): comma-separated list, e.g. react,typescript,node.js,docker.

The skills card recognizes many names and variants (case-insensitive; icons auto-loaded when available), including: react, node.js, typescript, javascript, python, go, rust, html, css, vue, angular, svelte, docker, graphql, mongodb, postgresql, redis, aws, gcp, tailwind, kubernetes, jenkins, next.js, express, java, kafka, argocd, cmake, c, c++, firebase.

🖼️ Use in Your GitHub Profile README

Replace <YOUR_BASE_URL> with your deployed URL (e.g., Vercel). These images update automatically and are cached for performance.

Top Languages

![Top Languages](https://<YOUR_BASE_URL>/languages?username=<YOUR_GITHUB_USERNAME>)

GitHub Overview (Commits/PRs/Issues)

![GitHub Overview](https://<YOUR_BASE_URL>/stats?username=<YOUR_GITHUB_USERNAME>)

Skills (customize your stack)

![Skills](https://<YOUR_BASE_URL>/skills?skills=react,typescript,node.js,docker,postgresql,redis)

Tips:

• GitHub may cache images aggressively; append a harmless version param when you update, e.g. .../stats?username=me&v=2.
• Place these under sections like “About Me” or “Tech Stack” in your README.

🛠️ Local Development

pnpm install
pnpm dev
# or
npm install
npm run dev

Environment variables must be present in .env for local runs.

☁️ Deploy (Vercel)

• Import this repo to Vercel.
• Add Environment Variables: GITHUB_API_TOKEN, GITHUB_USERNAME.
• Deploy. The included vercel.json routes all traffic to the serverless entry at app.js.

🔍 How It Works

• Data: GraphQL requests to GitHub (paginated) aggregate contributions and languages.
• Cache: 6-hour TTL with node-cache keyed per username.
• Cards: SVG generated by modules in cards/ — responsive and lightweight.
• Routes: Defined in routes/index.js with handlers in controllers/index.js.

⚠️ Troubleshooting

• /error exists to validate error handling; it intentionally throws an error.
• Empty cards? Ensure your token and username are correct and that the user has public contributions/repos.
• Skills icons missing? Some names don’t have icons; a gradient dot is used instead.

📦 Tech

• Node.js, node-fetch, dotenv, node-cache, GitHub GraphQL API, serverless via Vercel.

---