joachim97/letterboxd-wrapped

Letterboxd Wrapped

Generate a personalized “Wrapped” style report for any public Letterboxd profile. The app scrapes a user’s logged films and watchlist, enriches each title with TMDB metadata, and builds visuals plus a recommendation engine inspired by their taste.

Features

• —Username lookup with a stylish Letterboxd-inspired UI
• —Express API that scrapes watched films + watchlist (handles pagination) via Cheerio
• —TMDB enrichment with cached responses (genres, runtime, countries, crew, ratings)
• —Report sections: decade histogram, release year timeline, genre pie, runtime buckets, country diversity
• —“Controversial takes” (user rating vs TMDB average), director deep dives, and a watchlist recommender that blends TMDB recommendations with the learned taste profile
• —Share button (Web Share API / clipboard) and download-to-image button powered by html2canvas

Getting Started

1. 1.Install dependencies

   npm install

1. 1.Create a .env file (copy .env.example) and add a TMDB API key.

   TMDB_API_KEY=your_tmdb_api_key
   PORT=3000

1. 1.Start the development server

   npm run dev

1. 1.Visit http://localhost:3000, enter a Letterboxd username, and generate their report.

Deploying to Vercel

The repo includes a vercel.json that maps /api/* requests to the Express server and serves the /public folder statically. After setting the TMDB_API_KEY environment variable in Vercel, simply import the repo and deploy—no custom build commands required.

Notes

• —The scraper respects pagination limits; adjust maxFilms / maxWatchlist via query params if needed.
• —Watchlist scraping falls back gracefully if the list is private.
• —TMDB calls are cached in memory to reduce rate limiting.
• —Downloaded reports are static images of the rendered dashboard for easy sharing.