A self-hosted, static web application for viewing your exported Letterboxd data with movie posters from The Movie Database (TMDB).
- 📊 Dashboard - Overview of your viewing statistics and recent activity with interactive charts
- 📔 Diary - Browse all your logged films with ratings, dates, and tags
- �️ Watched - View all watched films with advanced filtering by star rating (5★, 4.5★, 4★, etc.)
- �🔖 Watchlist - View films you want to watch
- ⭐ Reviews - Read through all your written reviews
- 📝 Lists - Browse your custom movie lists with detailed viewer
- 📈 Interactive Statistics - Visual charts with clickable elements to filter and explore your data
- 🎯 Smart Filtering - Click on rating distribution chart segments to instantly filter watched films
- 🎬 Movie Posters - Automatically fetches high-quality posters from TMDB (with TV/miniseries fallback)
- 📱 Mobile-First Responsive Design - Optimized layouts for desktop, tablet, and mobile devices
- 🌙 Always-On Dark Mode - Enhanced dark theme with Letterboxd color scheme
- 👥 Multi-User Support - View data from multiple Letterboxd exports (optional)
- 🔧 Single User Mode - Automatic fallback when no users.json is present
The easiest way to get started:
- Download or clone this repository
- Extract your Letterboxd export ZIP file
- Copy all the CSV files directly into the
letterboxd-export/folder - The structure should look like:
letterboxd-viewer/ ├── index.html ├── app.js ├── style.css ├── README.md └── letterboxd-export/ ├── diary.csv ├── watched.csv ├── ratings.csv ├── reviews.csv ├── watchlist.csv ├── profile.csv ├── comments.csv ├── lists/ ├── likes/ ├── deleted/ └── orphaned/ - Open the application in a web browser (see Run the Application)
For viewing multiple users' data:
- Extract each user's Letterboxd export into separate folders within
letterboxd-export/ - Create
letterboxd-export/users.jsonwith your user configuration:
[
{
"id": "user1",
"displayName": "John Doe",
"folder": "JohnDoe",
"lastUpdated": "2024-01-15",
"lists": [
{ "name": "2023 Favorites", "file": "2023-favorites.csv" },
{ "name": "Watchlist", "file": "my-watchlist.csv" }
]
},
{
"id": "user2",
"displayName": "Jane Smith",
"folder": "JaneSmith",
"lastUpdated": "2024-01-10",
"lists": [
{ "name": "Horror Films", "file": "horror-collection.csv" }
]
}
]- The structure should look like:
letterboxed-viewer/ ├── index.html ├── app.js ├── style.css ├── README.md └── letterboxd-export/ ├── users.json ├── JohnDoe/ │ ├── diary.csv │ ├── watched.csv │ ├── (... all CSV files) │ └── lists/ └── JaneSmith/ ├── diary.csv ├── (... all CSV files) └── lists/
The app automatically detects your setup mode:
-
Single User Mode: If no
users.jsonfile is found, the app expects your Letterboxd export data to be placed directly in theletterboxd-export/folder. Perfect for personal use. -
Multi-User Mode: If a
users.jsonfile is present, the app will show a user selection screen and load data from user-specific folders as configured.
To display movie posters, you'll need a free API key from The Movie Database:
- Sign up at TMDB
- Go to API Settings
- Create a new API key (choose "Developer" option)
- Copy your API key
- Open
app.jsand replace the placeholder API key with your actual API key:this.TMDB_API_KEY = 'your_actual_api_key_here';
Note: The app will search for both movies and TV shows/miniseries when looking up titles, providing better poster coverage for all types of content.
This is a completely static web application that can be self-hosted on any web server or run locally.
# Navigate to the project directory
cd letterboxd-viewer
# Python 3
python -m http.server 8000
# Python 2
python -M SimpleHTTPServer 8000Then open http://localhost:8000 in your browser.
# Install a simple HTTP server
npm install -g http-server
# Navigate to project directory and run
cd letterboxd-viewer
http-server
# Or use npx (no installation required)
npx http-server- Install the "Live Server" extension in VS Code
- Right-click on
index.html - Select "Open with Live Server"
The application is compatible with any static web hosting service, including:
- Your own web server (Apache, Nginx, etc.)
- GitHub Pages (though not recommended due to API key exposure)
- Netlify (private repos recommended)
- Vercel (private repos recommended)
- Surge.sh
- Any hosting with file upload
Security Note: If using public hosting services, be aware that your TMDB API key will be visible in the source code. For public hosting, consider using private repositories or removing the API key (app will work without posters).
Note: The app needs to be served over HTTP/HTTPS (not opened as local files) due to CORS restrictions when loading CSV files.
The application automatically loads and processes these standard Letterboxd export files:
diary.csv- Your film diary with ratings, dates, tagswatched.csv- Simple list of all watched filmsratings.csv- Films you've ratedreviews.csv- Your written reviewswatchlist.csv- Films you want to watchprofile.csv- Your profile informationcomments.csv- Comments you've made
lists/- Your custom movie listslikes/- Films, reviews, and lists you've likeddeleted/- Deleted contentorphaned/- Orphaned content
The application uses Bootstrap 5 for the base styling with custom CSS in style.css. You can modify colors, fonts, and layout by editing this file.
The application is built with vanilla JavaScript and has a modular structure. Key areas for customization:
- Data Processing: Modify the
processData()method to add new data relationships - Views: Add new sections by creating corresponding HTML and JavaScript methods
- TMDB Integration: Extend the
getTMDBData()method to fetch additional movie information - Statistics: Add new charts and metrics in the
renderStats()method
You can modify these settings in app.js:
- TMDB API Key: Replace the placeholder value with your actual TMDB API key
- Display Limits: Currently set to 50 items per page for optimal performance
- Dark Mode: Automatically follows system preference with enhanced contrast and accessibility
- TMDB Integration: Searches both movies and TV shows for comprehensive poster coverage
- Make sure you've added your TMDB API key to
app.js - Check the browser console for API errors
- Verify your internet connection
- Note: The app searches both movies and TV shows, so most content should have posters
- Ensure the
letterboxd-exportfolder is in the correct location - Make sure you're accessing the site through a web server (not file://)
- Check that CSV files aren't corrupted
- Check the browser console for JavaScript errors
- Ensure all files are present and properly named
- Try refreshing the page or clearing browser cache
- Chrome/Chromium 70+
- Firefox 65+
- Safari 12+
- Edge 79+
This application runs entirely in your browser. Your Letterboxd data never leaves your device except for TMDB API calls to fetch movie posters (when API key is configured). No personal data is transmitted or stored on any external servers. When hosted on GitHub Pages or other static hosting, your CSV data remains completely private.
Feel free to contribute improvements! Some ideas:
- Additional chart types and interactive statistics
- Enhanced mobile navigation and user experience
- Export functionality for processed data
- Better TMDB matching for international titles
- Additional accessibility improvements
- Performance optimizations for large datasets
- More advanced filtering and search capabilities
MIT License - feel free to use and modify as needed.
- Letterboxd for the amazing platform and data export feature
- The Movie Database (TMDB) for movie metadata and posters
- Bootstrap for the UI framework
- Chart.js for statistics visualization