GitHub Wrapped

Your year in code, beautifully visualized.

Generate a personalized "Spotify Wrapped"-style summary of your GitHub activity. See your commits, PRs, top languages, coding patterns, and fun stats - all in a shareable, screenshot-friendly format.

Live Demo: your-github-wrapped.vercel.app

Features

• No Authentication Required - Works with public GitHub data only
• Instant Generation - Just enter any GitHub username
• Year Selection - View stats from 2008-present
• Beautiful Bento Grid Layout - Compact, shareable design
• Download as Image - Save and share on social media
• Share Buttons - One-click sharing to X (Twitter) and LinkedIn
• Fun Insights - Night Owl/Early Bird, Weekend Warrior, coding streaks, and more
• Responsive Design - Works great on desktop and mobile
• Production-Ready - Rate limiting, caching, security headers

Stats Displayed

Stat	Description
Total Commits	All commits across your repositories
Pull Requests	PRs you've authored
Issues	Issues you've created
Stars Earned	Stars on your repositories
Top Languages	Your most-used programming languages
Top Repositories	Repos with most commits
Longest Streak	Consecutive days of coding
Night Owl/Early Bird	Based on commit timestamps
Weekend Warrior	Percentage of weekend commits
Most Active Day	Your busiest day of the week
Developer Personality	Fun personality based on your habits

Tech Stack

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS v4
• Validation: Zod
• Image Export: html-to-image
• API: GitHub REST API

Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

1. Clone the repository:

git clone https://github.com/yourusername/github-wrapped.git
cd github-wrapped

2. Install dependencies:

npm install

3. Create environment file:

cp .env.example .env.local

4. Add your GitHub token to .env.local:

GITHUB_TOKEN=your_github_personal_access_token

Important: A GitHub Personal Access Token is required for production use. Without it, you're limited to 60 API requests/hour. With a token, you get 5,000 requests/hour.

5. Start the development server:

npm run dev

6. Open http://localhost:3000 in your browser.

Creating a GitHub Token

1. Go to GitHub Settings > Developer Settings > Personal Access Tokens
2. Click "Generate new token (classic)"
3. Give it a name (e.g., "GitHub Wrapped")
4. No scopes needed - leave all boxes unchecked (public data only)
5. Click "Generate token"
6. Copy the token and add it to your .env.local

Environment Variables

Variable	Required	Description
GITHUB_TOKEN	Yes*	GitHub Personal Access Token for API access

*Required for production. Without it, rate limits are very restrictive (60 requests/hour).

API Reference

GET /api/wrapped/[username]

Fetch wrapped data for a GitHub user.

Parameters:

• username (path) - GitHub username (required)
• year (query) - Year for statistics (optional, defaults to current year)

Response:

{
  "success": true,
  "data": {
    "user": { "login": "...", "avatar_url": "...", ... },
    "year": 2025,
    "stats": { "totalCommits": 0, "totalPRs": 0, ... },
    "monthlyData": [...],
    "topRepos": [...],
    "languages": [...],
    "funStats": { ... },
    "contributions": { ... }
  },
  "meta": {
    "requestId": "req_...",
    "generatedAt": "2025-01-01T00:00:00.000Z"
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "GitHub user \"xyz\" was not found.",
    "requestId": "req_..."
  }
}

Architecture

See ARCHITECTURE.md for detailed information about:

• Project structure
• Data flow
• Caching strategy
• Rate limiting

Security

See SECURITY.md for detailed information about:

• Token handling
• Security headers
• Rate limiting
• Input validation

Deployment

Vercel (Recommended)

1. Click the button above or import your repo to Vercel
2. Add GITHUB_TOKEN as an environment variable
3. Deploy!

Other Platforms

This is a standard Next.js app that can be deployed anywhere that supports Node.js:

npm run build
npm start

Project Structure

src/
├── app/
│   ├── api/wrapped/[username]/   # API route for fetching data
│   ├── wrapped/[username]/       # Results page
│   ├── layout.tsx                # Root layout with metadata
│   ├── page.tsx                  # Landing page
│   └── globals.css               # Global styles & theme
├── components/
│   ├── wrapped/
│   │   └── BentoWrapped.tsx      # Main wrapped card component
│   └── LoadingState.tsx          # Loading animation
├── domain/
│   └── wrapped/                  # Pure domain logic (aggregators)
├── services/
│   └── wrappedService.ts         # Business logic orchestration
└── lib/
    ├── github/                   # GitHub API client
    ├── errors.ts                 # Centralized error handling
    ├── validation.ts             # Zod schemas
    ├── rateLimit.ts              # Rate limiting
    └── types.ts                  # TypeScript interfaces

Limitations

• Only works with public GitHub data (private repos are not accessible)
• GitHub Events API only returns the last 90 days of events
• Commit data is fetched from top 30 repositories to avoid rate limits
• Some statistics are approximations based on available data
• In-memory caching is per-process (not shared across serverless instances)

Contributing

Contributions are welcome! Feel free to:

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

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Uday Mehtani

• LinkedIn: linkedin.com/in/udaymehtani
• GitHub: github.com/uday03meh

---

Made with love and lots of coffee.

If you found this useful, consider giving it a star!