Skip to content
LebbitheplowPublic

About

Discover games you already own — but haven't played yet.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ShelfLife

ShelfLife logo
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.

Home

ShelfLife home page

Profile

ShelfLife recommendations page

Steam Store

ShelfLife Steam Store tab

Features

  • 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

Tech Stack

  • 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)

Setup

Prerequisites

Install

git clone https://github.com/Lebbitheplow/shelflife.git
cd shelflife
npm install
cp .env.example .env

Edit .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

Run

# Production
npm start

# Development (auto-restarts on file changes)
npm run dev

Then visit http://localhost:3233 and paste your Steam profile URL.

Docker (recommended)

# 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 -d

The data/ directory is mounted as a volume so your cache persists across container restarts.

Updating

docker compose pull && docker compose up -d

How It Works

  1. You enter a Steam profile URL or custom ID
  2. ShelfLife fetches your owned games via the Steam Web API
  3. Metadata (tags, genres, ratings, trailers) is pulled from SteamSpy and the Steam Store API and cached locally
  4. Your positively-reviewed games are fetched and weighted 1.5x in scoring
  5. 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
  6. 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
  7. The featured Top 20 is diversified so one studio or series can't crowd it out
  8. Results are cached — subsequent visits load instantly; a background job refreshes active users daily
  9. 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

Configuration

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)

Notes

  • 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

License

MIT

About

Discover games you already own — but haven't played yet.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages