⚡ Fancy Github Stats

An extensible, high-performance API server built with Next.js that generates dynamic, customizable SVG statistics cards for your GitHub profile README. Features interactive telemetry components, language spectrum charts, contribution streak tracking, customizable themes, modular card layouts, and built-in server-side caching.

Example: See below

---

🚀 Deploy your own

1. One-Click Deploy (Fastest)

Click the button below to deploy your own instance directly to Vercel. Vercel will clone this repo straight into your GitHub account, prompt you for the GITHUB_TOKEN environment variable, and deploy-no manual forking required.

During setup Vercel will:

1. Ask you to sign in / connect GitHub
2. Create a new repo in your account with this code
3. Prompt you for GITHUB_TOKEN (see Getting a token below)
4. Deploy it

2. Fork, then import

1. Click Fork at the top of this repo on GitHub
2. Go to vercel.com/new and import your fork
3. Before deploying, expand Environment Variables and add GITHUB_TOKEN
4. Click Deploy

Both options end up in the same place - pick whichever flow you prefer.

---

🪪 Using the card

In a GitHub profile README

![My GitHub Stats](https://your-app.vercel.app/?username=GITHUB_USERNAME)

On a personal website

<img
  src="https://your-app.vercel.app/?username=GITHUB_USERNAME"
  alt="GitHub stats"
/>

As a direct link

Just open the URL in a browser — it's a valid standalone image.

---

🎨 Themes & Customization

Customize your stats card by passing query parameters directly in the URL:

https://your-domain.com/?username=GITHUB_USERNAME&theme=signal-lab&hide_header=false

Available Themes & Cards

Query Value	Layout / Type	Description
signal-lab (Default)	Full Dashboard	High-tech cyberpunk telemetry dashboard
dracula	Full Dashboard	Dracula color palette
nord	Full Dashboard	Arctic, north-bluish Nord color palette
matrix	Full Dashboard	Terminal green matrix theme
cyberpunk	Full Dashboard	Neon blue and magenta palette
compact	Compact Card	Sleek single-card summary with metric pillars
compact-dracula	Compact Card	Compact with Dracula color pallet
compact-nord	Compact Card	Compact with Nord color pallet
grid	Modern Grid	Card-based grid layout with progress indicators
grid-cyber	Modern Grid	Grid with Cyberpunk color pallet
languages	Single Card	Dedicated Top Languages bar & breakdown chart
stats	Single Card	Dedicated core GitHub statistics card
streak	Single Card	Dedicated contribution streak & flame counter

See the how different themes look in the Example section.

⚙️ Query Parameters

Parameter	Type	Default	Description
username	string	Required	Your GitHub username
theme	string	signal-lab	Visual theme or specialized card variant
hide_header	boolean	false	Set to true or 1 to hide the top avatar/profile header

---

🛠️ Self-Hosting & Local Setup

Prerequisites

• Node.js: 18.x or higher
• GitHub Personal Access Token (PAT): Requires read:user and repo permissions to query the GitHub GraphQL API.

1. Clone & Install

git clone https://github.com/tajultonim/fancy-github-stats.git
cd fancy-github-stats
npm install

2. Configure Environment Variables

Create a .env.local file in the project root:

GITHUB_TOKEN=your_github_personal_access_token_here

3. Run Locally

npm run dev

Open http://localhost:3000/?username=YOUR_USERNAME in your browser to test the SVG output.

---

#️⃣ Getting a token

The card reads your GitHub data via GraphQL, which needs a token.

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (Classic), or follow this link
2. Click Generate new token > Generate new token (Classic)
3. Put a note as you please
4. Under Select Scopes, select repo, read:user, user:email
5. Generate the token and copy it - you won't see it again Paste it into the GITHUB_TOKEN field when prompted by the deploy flow or add it in your Vercel project's Settings → Environment Variables if deploying from a repo.

---

🛠️ Architecture & Contributing

This project uses the Strategy Pattern to separate API routing, GitHub GraphQL data fetching, and SVG layout rendering.

├── app/
│   └── route.js              # Main API controller (handles /?username=...)
├── lib/
│   ├── github.js             # GraphQL client, cache, and metrics computation
│   └── layouts/
│       ├── registry.js       # Central layout and theme resolver engine
│       ├── signalLab.js      # Dual-column telemetry dashboard
│       ├── compact.js        # Compact card layout
│       ├── modernGrid.js     # Grid card layout
│       ├── singleLanguage.js # Language card
│       ├── singleStats.js    # Stats card
│       └── singleStreak.js   # Streak card

Adding a New Theme / Color Palette

1. Open the target layout file (e.g., lib/layouts/compact.js).
2. Add your new palette under the palettes object:

myTheme: {
  bg: "#1a1a1a",
  card: "#262626",
  border: "#404040",
  textPrimary: "#ffffff",
  textSecondary: "#a3a3a3",
  accent: "#3b82f6",
}

3. Register the theme alias in lib/layouts/registry.js:

"compact-custom": { layout: "compact", palette: "myTheme" }

Adding a Completely New Layout

1. Create a new layout file under lib/layouts/myNewLayout.js.
2. Implement the strategy interface:

export const myNewLayout = {
  palettes: {
    default: {
      /* colors */
    },
  },
  render(stats, colors, options = {}) {
    // Return SVG string
  },
};

3. Export and register it in lib/layouts/registry.js.

---

📝 Examples

Full dashboard

1. signal-lab, 2.dracula

2. nord, 4. matrix

3. cyberpunk

Card Based

1. compact, 2. compact-dracula

3. compact-nord

4. grid, 5. grid-cyber

Single Card

1. stats, 2. languages

3. streak

📄 License

Copyright © 2026 Tajul Tonim

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.