📺 Trakt Contribution Graph

Transform your Trakt watch history into a beautiful GitHub-style contribution graph

---

✨ Features

Feature	Description
🎨 Light & Dark Themes	Automatically adapts to GitHub's theme preference
📊 Activity Heatmap	GitHub-style contribution graph showing movie & episode activity
👤 Profile Integration	Shows profile picture, display name, and all-time stats
🎬 Content Filtering	Display movies only, shows only, or everything together
📅 Multi-Year Support	Generate vertical graphs spanning multiple years
🎯 Streak Highlighting	Hover over stats to highlight your longest activity streak
💬 Interactive Tooltips	Hover over cells to see specific titles watched that day
🏎️ Fast & Efficient	Uses the Trakt API with intelligent pagination and caching
🔄 Daily Updates	Automated updates via GitHub Actions

---

📸 Examples

Movies Only

Episodes Only

---

🚀 Quick Start

1. Fork this Repository

Click the Fork button at the top-right of this page.

2. Configure Trakt API

1. Go to Trakt API App Setup and create a new application.
2. For Redirect URI, use urn:ietf:wg:oauth:2.0:oob.
3. Copy your Client ID.
4. In your GitHub repository, go to Settings → Secrets and variables → Actions.
5. Add a new Repository secret:
   • Name: TRAKT_API_KEY
   • Value: (Your Trakt Client ID)

3. Update Your Username

Edit .github/workflows/update-trakt-graph.yml:

env:
  TRAKT_USERNAME: "YOUR_TRAKT_USERNAME"

4. Enable GitHub Actions

Go to Actions tab → Enable workflows if prompted.

5. Run the Workflow

The graph updates daily at midnight UTC, or trigger manually via the Actions tab.

---

📖 CLI Usage

# Install dependencies
npm install

# Set your API Key (Client ID)
$env:TRAKT_API_KEY = "your_client_id" # Windows PowerShell
# export TRAKT_API_KEY="your_client_id" # Linux/macOS

# Basic usage
node src/cli.js <username>

# With options
node src/cli.js <username> [options]

Arguments

Flag	Description	Default
-y <years>	Year(s) to generate, comma-separated (e.g. 2025,2024)	Current year
-t <type>	Content type: movies, shows, or all	all
-w <day>	Week start: sunday or monday	sunday
-o <path>	Output path (without extension)	images/github-trakt
-g <bool>	Enable username gradient: true or false	true
-p	Export PNG files in addition to SVG	Disabled

---

🔧 GitHub Actions Setup

1. Repository Secret

To use the automated workflow, you must provide your Trakt API Key as a GitHub Secret:

1. Go to your repository on GitHub.
2. Navigate to Settings → Secrets and variables → Actions.
3. Create a New repository secret.
4. Set the name to TRAKT_API_KEY and the value to your Trakt Client ID.

2. Workflow File

Full configuration is available in the workflow file header:

env:
  TRAKT_USERNAME: "TheLagacyMiner"
  YEARS: ""              # e.g. "2025,2024" or empty for current
  CONTENT_TYPE: "all"    # "movies", "shows", or "all"
  WEEK_START: "sunday"
  GRADIENT: "true"

---

📂 Project Structure

trakt-graph/
├── .github/
│   └── workflows/
│       └── update-trakt-graph.yml
├── fonts/               # Required for SVG text measurement
├── images/              # Target directory for generated graphs
├── src/
│   ├── cli.js           # CLI entry point
│   ├── fetcher.js       # Trakt API interaction
│   ├── generator.js     # SVG layout and rendering
│   ├── stats.js         # Activity calculations
│   └── exporter.js      # PNG export (Sharp)
├── package.json
└── README.md

---

🖼️ Embed in Your README

<p align="center">
  <a href="https://trakt.tv/users/YOUR_TRAKT_USERNAME/" target="_blank">
    <picture>
      <source
        media="(prefers-color-scheme: dark)"
        srcset="https://github.com/YOUR_GITHUB_USERNAME/trakt-graph/blob/main/images/github-trakt-dark.svg"
      />
      <source
        media="(prefers-color-scheme: light)"
        srcset="https://github.com/YOUR_GITHUB_USERNAME/trakt-graph/blob/main/images/github-trakt-light.svg"
      />
      <img
        alt="Trakt contribution graph"
        src="https://github.com/YOUR_GITHUB_USERNAME/trakt-graph/blob/main/images/github-trakt-light.svg"
      />
    </picture>
  </a>
</p>

---

🛠️ Requirements

• Node.js v18 or higher
• Trakt API Key (Client ID)
• GitHub Actions enabled for automation

---

🤝 Contributing & License

MIT License. Contributions are welcome!