🎬 jellyfin-widget-proxy

---

jellyfin-widget-proxy is a custom integration for the Homepage dashboard that displays a beautiful, interactive poster grid of recently added movies and TV shows from your Jellyfin server via a lightweight proxy.

---

✨ Features

• Dynamic Poster Grid - Automatically fetches and displays the latest high-quality media art.
• Responsive Design - Adaptive layout optimized for both desktop and mobile views.
• Direct Linking - Click any poster to jump straight to that title in your Jellyfin web UI.
• TV Episode Grouping - Multiple new episodes of the same series are deduplicated into one entry with a count badge.
• Lightweight Proxy - Python/Flask backend that handles API authentication and cross-origin requests securely.
• Seamless Card Integration - Poster grid renders inside the Homepage service card, respecting rounded corners and card styling.

---

🖼️ Preview

---

🚀 Installation & Setup

1. Deploy the Proxy

The proxy handles Jellyfin API authentication server-side and serves the data to the Homepage widget.

Option A: Docker Compose (Recommended)

services:
  jellyfin-widget-proxy:
    image: ghcr.io/chr0nzz/jellyfin-widget-proxy:latest
    container_name: jellyfin-widget-proxy
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - JELLYFIN_URL=https://jellyfin.yourdomain.com
      - JELLYFIN_API_KEY=your_api_key_here
      - JELLYFIN_USER_ID=your_user_hex_id_here
      - LIMIT=6

Option B: Docker Run

docker run -d \
  --name jellyfin-widget-proxy \
  -p 5000:5000 \
  -e JELLYFIN_URL="https://jellyfin.yourdomain.com" \
  -e JELLYFIN_API_KEY="your_api_key_here" \
  -e JELLYFIN_USER_ID="your_user_hex_id_here" \
  -e LIMIT="6" \
  ghcr.io/chr0nzz/jellyfin-widget-proxy:latest

---

🛠 Build from Source

git clone https://github.com/chr0nzz/jellyfin-widget-proxy.git
cd jellyfin-widget-proxy
docker build -t jellyfin-widget-proxy:local .
docker run -d \
    --name jellyfin-widget-proxy \
    -p 5000:5000 \
    -e JELLYFIN_URL="https://jellyfin.yourdomain.com" \
    -e JELLYFIN_API_KEY="your_api_key_here" \
    -e JELLYFIN_USER_ID="your_user_hex_id_here" \
    -e LIMIT="6" \
    jellyfin-widget-proxy:local

---

🏠 Homepage Configuration

services.yaml

Add a service entry with the required id. The id is how the script locates and injects the poster grid into the correct card.

- Media:
    - Latest Movies & Shows:
        id: jellyfin-recently-added
        #href: https://jellyfin.yourdomain.com
        #icon: sh-jellyfin

custom.js

Copy the contents of custom.js into your Homepage config/custom.js.

Important

Update the proxyApiUrl variable at the top of the file to point to your proxy's address:

const proxyApiUrl = "http://192.168.1.100:5000/recent";

custom.css

Copy the contents of custom.css into your Homepage config/custom.css.

The CSS handles the poster grid layout, card expansion, hover effects, and badge styling.

---

⚙️ Environment Variables

Variable	Description	Example
JELLYFIN_URL	Full URL of your Jellyfin instance	https://jellyfin.domain.com
JELLYFIN_API_KEY	Admin API Key from Jellyfin Dashboard > API Keys	7a8b9c0d...
JELLYFIN_USER_ID	User ID to fetch recently added items for	00a11b22...
LIMIT	Number of posters to display	6

---

🤝 Contributing

Issues and pull requests are welcome. Feel free to open a ticket if you have suggestions or run into problems.

---

📄 License

This project is licensed under the GNU General Public License v3.0.

Copyright (C) 2026 chronzz (https://github.com/chr0nzz)