Steam Stats

Personal Steam analytics dashboard — library playtime, spend vs shelf value, and a playtime panorama collage. Runs locally with your own Account Data; nothing is uploaded to a third-party server.

Features

Library

• Hours / Recent / A–Z shelf views with search
• Playtime panorama (30m+ titles, sized by hours, downloadable PNG)
• Most-played hero + Steam Family Library titles when available

Value

• What you paid vs current / historical-low shelf value
• Cost per hour, unplayed spend, gifts, monthly habits
• Market quote refresh (Steam store + CheapShark)

Requirements

• Node.js 20+ (recommended)
• npm (or compatible package manager)
• A Steam account (you log in once in a local browser window)
• Optional: Steam Web API key for richer library APIs

Automatic setup (one command)

Clone, install, Steam login, fetch your data, and open the dashboard:

git clone https://github.com/parthUltra/steam-stats.git && cd steam-stats && npm install && npm run launch

A browser opens for Steam login (Steam Guard if needed). When that finishes, the app starts and your default browser opens to http://localhost:3000.

Faster (skips market price refresh):

git clone https://github.com/parthUltra/steam-stats.git && cd steam-stats && npm install && npm run launch:fast

Press Ctrl+C in the terminal to stop the server.

Already cloned? Just run npm run launch from the project folder.

Manual setup

For users who want each step separate.

Install

git clone https://github.com/parthUltra/steam-stats.git
cd steam-stats
npm install
npx playwright install chromium
cp .env.example .env.local   # optional: STEAM_API_KEY, ISTHEREANYDEAL_API_KEY

Fetch & parse data

npm run fetch:account-data   # log into Steam in the opened window
npm run parse:account-data
npm run fetch:owned-games

Optional: transactions, prices & older gifts

npm run fetch:transactions
npm run refresh:prices
npm run sync:gifts-gmail     # opens Gmail in a browser; stores gift emails locally

On the Value tab, Gifts I received shows Steam Gift/Guest Pass licenses immediately. Sync from Gmail opens your browser, searches Steam “You’ve received a gift” emails (e.g. Your friend X has given you GAME on Steam), and stores them in data/gifts-received.json (title, sender persona, gift link, date). Gmail session files live under .gmail-session/.

Run the app

npm run dev

Open http://localhost:3000.

Scripts reference

Script	Purpose
npm run launch	All-in-one: login → fetch → parse → prices → open dashboard
npm run launch:fast	Same as launch, skip price refresh
npm run dev	Next.js dev server only
npm run build / npm start	Production build & serve
npm run fetch:account-data	Steam login + Account Data HTML
npm run parse:account-data	Parse HTML → JSON
npm run fetch:owned-games	Full library + family playtime
npm run fetch:transactions	Transaction line-item prices
npm run refresh:prices	Refresh data/price-cache.json (Steam live + ITAD INR / CheapShark USD lows)
npm run lint	ESLint

Configuration

Copy .env.example → .env.local:

Variable	Required	Description
STEAM_API_KEY	No	Steam Web API key. Improves some library endpoints; session-based fetch already covers most playtime.
ISTHEREANYDEAL_API_KEY	No	Prefer Value → Get India lows (paste key from ITAD Apps). Stored in data/itad-credentials.json.

Privacy & security

• Runs entirely on your machine. Account HTML, session cookies, and caches stay local.
• Never commit .env.local, .steam-session/, samples/, or data/ — they are gitignored.
• Session cookies in .steam-session/ can access your Steam account. Treat them like passwords.
• Do not share screenshots that include purchase totals or Steam IDs if you care about privacy.

Project layout

src/
  app/                 # Next.js App Router + API
  components/          # Dashboard UI (Library, Value, Panorama)
  components/ui/       # shadcn/ui primitives
  lib/
    account-data/      # Account Data HTML parsers
    analytics/         # Spending, valuation, cost/hr, dashboard
    pricing/           # Market quote cache
    steam/             # Owned games, artwork, DLC parents
scripts/               # CLI fetch / parse / refresh tools
samples/               # Local HTML + parsed JSON (gitignored)
data/                  # Local price / artwork caches (gitignored)

Troubleshooting

Issue	Fix
Dashboard empty / parse errors	Re-run fetch:account-data then parse:account-data
Few games / missing hours	Run fetch:owned-games after a valid session
Login window times out	Complete Steam Guard within ~10 minutes; re-run fetch
Prices missing	npm run refresh:prices (first run can take a while)
Playwright missing browser	npx playwright install chromium

License

MIT — see LICENSE.