https://github.com/nichtlegacy/trakt-graph
Generates a GitHub-style contribution graph based on your Trakt watch history. Uses Node.js to fetch API data, process entries, and create daily updated SVG visuals via GitHub Actions.
https://github.com/nichtlegacy/trakt-graph
api contribution-graph github-profile heatmap javascript node-js svg trakt
Last synced: 2 months ago
JSON representation
Generates a GitHub-style contribution graph based on your Trakt watch history. Uses Node.js to fetch API data, process entries, and create daily updated SVG visuals via GitHub Actions.
- Host: GitHub
- URL: https://github.com/nichtlegacy/trakt-graph
- Owner: nichtlegacy
- License: mit
- Created: 2025-03-28T19:16:09.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-26T01:23:56.000Z (2 months ago)
- Last Synced: 2026-04-26T03:28:34.491Z (2 months ago)
- Topics: api, contribution-graph, github-profile, heatmap, javascript, node-js, svg, trakt
- Language: JavaScript
- Homepage:
- Size: 65.6 MB
- Stars: 1
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 📺 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](https://trakt.tv/oauth/applications) 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`:
```yaml
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
```bash
# 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
# With options
node src/cli.js [options]
```
### Arguments
| Flag | Description | Default |
|------|-------------|---------|
| `-y ` | Year(s) to generate, comma-separated (e.g. `2025,2024`) | Current year |
| `-t ` | Content type: `movies`, `shows`, or `all` | `all` |
| `-w ` | Week start: `sunday` or `monday` | `sunday` |
| `-o ` | Output path (without extension) | `images/github-trakt` |
| `-g ` | 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:
```yaml
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
```html
```
---
## 🛠️ Requirements
- **Node.js** v18 or higher
- **Trakt API Key** (Client ID)
- **GitHub Actions** enabled for automation
---
## 🤝 Contributing & License
MIT License. Contributions are welcome!