Discover games you already own — but haven't played yet.
ShelfLife connects to your Steam library and surfaces personalized picks from your backlog, scored by what you demonstrably love. Your shelf comes first; a separate Steam Store tab ranks games you don't own against the same taste profile, with current prices and sale discounts.
- Spotlight hero — your single best pick with its key art, plus an "Up Next" queue
- Top Picks — scored recommendations based on your playtime patterns, tags, developers, and Steam reviews
- Never Touched — games you own but have zero playtime
- Almost Started — games with under 2 hours played
- Friends Are Playing — games your friends play that you've never launched (when your friends list is public)
- By Genre — browse your backlog filtered by genre
- Time to beat — IGDB main-story estimates on each card, plus total hours to clear your backlog
- Detail Modal — game art, trailer video (Steam HLS or YouTube fallback), ratings, tags, and why it was recommended
- Personalized reasons — "Because you loved X", "More from Y (you loved Z)", franchise detection
- Steam Store tab — games you don't own, browsed from the store by your top tags and ranked with the same Shelf Score; shows price, sale discount, and free-to-play picks. Prices use
STORE_COUNTRY(default US) - Mobile friendly — responsive layout down to 320px
- Runtime: Node.js 23
- Framework: Express + EJS
- Database: SQLite via Node.js built-in
node:sqlite(metadata cache, library cache, rec cache) - APIs: Steam Web API, SteamSpy, Steam Store appdetails, YouTube Data API v3
- Video: HLS.js for Steam HLS trailers; YouTube iframe embed as fallback for games with no Steam trailer
- Auth: None required — just paste your Steam profile URL (must be public)
- Node.js >= 23.4.0
- A Steam Web API key
- A YouTube Data API v3 key (optional but recommended — used as a trailer fallback for older games that Steam has no trailer for)
git clone https://github.com/Lebbitheplow/shelflife.git
cd shelflife
npm install
cp .env.example .envEdit .env with your values:
STEAM_API_KEY=your_steam_web_api_key_here
PORT=3233
YOUTUBE_API_KEY=your_youtube_data_api_v3_key_here
IGDB_CLIENT_ID=your_twitch_client_id_here
IGDB_CLIENT_SECRET=your_twitch_client_secret_here# Production
npm start
# Development (auto-restarts on file changes)
npm run devThen visit http://localhost:3233 and paste your Steam profile URL.
# 1. Download the compose file
curl -o docker-compose.yml https://raw.githubusercontent.com/Lebbitheplow/shelflife/master/docker-compose.yml
# 2. Edit the environment variables
nano docker-compose.yml
# 3. Start
docker compose up -dThe data/ directory is mounted as a volume so your cache persists across container restarts.
docker compose pull && docker compose up -d- You enter a Steam profile URL or custom ID
- ShelfLife fetches your owned games via the Steam Web API
- Metadata (tags, genres, ratings, trailers) is pulled from SteamSpy and the Steam Store API and cached locally
- Your positively-reviewed games are fetched and weighted 1.5x in scoring
- A preference profile is built from your playtime: IDF-weighted tag weights, genre/developer/category weights, franchise signals, recency (games played in the last 90 days count more), and a small penalty for tags shared with games you launched briefly and abandoned
- Every unplayed/barely-played game is scored against that profile: tag/genre/developer/category overlap, item-similarity to the specific games you loved most (Jaccard over tags), Metacritic, Steam reviews (Wilson lower bound, so small samples don't inflate), and release recency
- The featured Top 20 is diversified so one studio or series can't crowd it out
- Results are cached — subsequent visits load instantly; a background job refreshes active users daily
- The Steam Store tab searches the storefront by your strongest tags (plus current specials), drops games you own, fetches details and prices for the best ~75 candidates, and scores them the same way. It rebuilds every 12 hours so sale prices stay current
| Variable | Description |
|---|---|
STEAM_API_KEY |
Steam Web API key (required) |
PORT |
Port to listen on (default: 3233) |
IGDB_CLIENT_ID / IGDB_CLIENT_SECRET |
Twitch/IGDB credentials (optional) — enables franchise detection and time-to-beat estimates |
YOUTUBE_API_KEY |
YouTube Data API v3 key (optional) — falls back to YouTube search for games with no Steam trailer. Requires an IP address restriction (not HTTP referrer) since requests are made server-side. |
STORE_COUNTRY |
Two-letter Steam store country code for prices (default: us) |
REFRESH_INTERVAL_HOURS |
How often active users' data is refreshed in the background (default: 24) |
- Your Steam profile must be set to Public for the library fetch to work
- First visit may take 1–2 minutes for large libraries (2000+ games)
- Metadata is cached locally in
data/shelflife.db— subsequent visits are near-instant - Trailers are fetched on-demand when you open a game's detail modal
MIT


