Reading Stats Badge Generator

Generate beautiful, dynamic GitHub README badges that showcase your reading statistics. Track your books, favorites, and currently reading status with automatically updating badges.

Sample:

Demo:

https://youtu.be/bT8tFInxECY

Features

• Beautiful SVG Badges: Custom-designed badges with modern styling
• Dynamic Updates: Badges update automatically when you change your data
• Persistent Storage: Book data saved securely in Redis database
• Easy Deployment: Deploy to Render with simple setup
• Book Search: Search and add books from Open Library
• Rich Statistics: Display total books, top genres, favorite authors
• GitHub Integration: Perfect for GitHub README profiles

Quick Start

Deploy Your Own Instance

1. Fork this repository

2. Create a Render account at render.com

3. Create a new Web Service:

   • Connect your GitHub repository
   • Set the following configuration:
     • Root Directory: .
     • Build Command: ./build.sh
     • Start Command: npm start

4. Set up your database:

   • Create an Upstash Redis database at upstash.com
   • Copy the REST URL and token

5. Configure environment variables in Render:

   UPSTASH_REDIS_REST_URL=https://your-db.upstash.io
   UPSTASH_REDIS_REST_TOKEN=your_token_here
   

6. Deploy: Render will build and deploy your application

7. Use your application:

   • Visit your deployed site: https://your-app.onrender.com
   • Add books to your reading library
   • Set favorites and currently reading
   • Generate your badge data

8. Get your badge URL:

   https://your-app.onrender.com/api/badge/main
   

9. Add to your GitHub README:

   ![Reading Stats](https://your-app.onrender.com/api/badge/main)

How It Works

1. Add Books: Search and add books to your reading library
2. Set Preferences: Mark favorites and currently reading books
3. Generate Badge: Create your personalized reading stats badge
4. Automatic Updates: Badge updates whenever you change your data
5. Permanent Link: Same URL always shows your latest stats

API Reference

Save Reading Data

POST /api/generate-badge
Content-Type: application/json

{
  "username": "your-github-username",
  "books": ["book-id-1", "book-id-2"],
  "favorites": ["book-id-1"],
  "currentlyReading": "book-id-2"
}

Load Reading Data

GET /api/user-data

Response: Returns saved reading data or 404 if no data exists

Get Badge

GET /api/badge/main
Accept: image/svg+xml

Search Books

GET /api/search-books?q=search-term

Get Book Details

GET /api/books/:id

Response: Returns complete book details with resolved author names

{
  "id": "OL14926019W",
  "title": "The Lord of the Rings",
  "authors": ["J.R.R. Tolkien"],
  "genres": ["Fantasy", "Adventure"],
  "pageCount": 0
}

Tech Stack

• Backend: Node.js, Fastify
• Frontend: React, Vite, Tailwind CSS
• Database: Upstash Redis
• Badge Generation: SVG.js
• Book Data: Open Library API
• Deployment: Render

Local Development

# Clone the repository
git clone https://github.com/your-username/reading-stats.git
cd reading-stats

# Install dependencies
npm install
cd frontend && npm install && cd ..

# Set up environment variables
# Create .env.local with your Redis credentials
UPSTASH_REDIS_REST_URL=https://your-db.upstash.io
UPSTASH_REDIS_REST_TOKEN=your_token_here

# Start development servers
npm run dev          # Backend on port 3000
cd frontend && npm run dev  # Frontend on port 5173

Customization

Badge Styling

Modify badge appearance in src/badge/generator.ts:

• Colors, fonts, layout
• Statistics display
• Icon styles

UI Theming

Update styles in frontend/src/:

• Tailwind CSS classes
• Component styling
• Responsive design

Badge Statistics

The badge displays:

• Total Books: Number of books in your library
• Top Genre: Most read genre
• Top Author: Most read author
• Currently Reading: Your current book with cover

Privacy & Security

• Book data stored securely in Redis
• No personal information collected
• SVG badges served with cache control
• Environment variables for sensitive data

Acknowledgments

• Open Library for book data

---

Happy Reading!

Show off your reading journey with dynamic, beautiful badges!