Home Run Derby
A web app for running a fantasy baseball Home Run Derby league. Owners pick players from tiered groups, and the site tracks every team's home runs all season: standings, monthly races, player rankings, optimal lineups, win odds, and a monthly standings workbook emailed to each owner.
Scoring comes straight from MLB StatsAPI game logs, refreshed nightly, so the app matches the league host's own workbook game for game.
Features
- League-scoped public site at
/{league}: overall and monthly standings, player rankings by group, optimal lineups, win odds, rules, and a page for every team. Past seasons are available with ?season=YYYY.
- Self-service entry form: team name, owner name and email, and one or more picks per group. Teams can also be imported from the host's workbook.
- Nightly scoring sync: re-imports every pool player's regular-season game log and sums home runs by official game date for each scoring period. Re-running fixes past months automatically (late-added players, corrected MLB IDs, missed days).
- Forecasts and win odds: each day the odds job records every rostered player's projection, injury status and model version, so end-of-season reviews don't need to reconstruct anything.
- Monthly workbook emails: two days after each month closes, a host-format Excel workbook (General Prizes, Players, Picks, one tab per month, YTD) goes to every owner via Resend. One email per person covers all their teams, sends are logged per owner so a timed-out run resumes without double-sending, and every email carries a signed unsubscribe link.
- Admin area at
/admin: league and season settings, owner emails, entry status, exports, manual sync, and batch ingest.
- Multi-league and multi-season: a league has one season per MLB year; groups, pools, entries and standings all belong to a season. Each league gets its own URL and shares MLB data with the others.
Tech stack
| Layer | Details |
|---|
| Framework | Next.js 16 (App Router), React 19, TypeScript |
| Database | PostgreSQL with Prisma 7 (@prisma/adapter-pg) |
| Styling and UI | Tailwind CSS 4, Arc UI components (src/components/arc/), lucide-react, motion |
| Validation | Zod |
| Spreadsheets | ExcelJS |
| Email | Resend |
| Data | MLB StatsAPI game logs |
| Tests | Vitest |
| Hosting | Vercel (with Vercel Cron) |
Getting started
Prerequisites
- Node.js 20.19 or later
- A PostgreSQL database
Setup
git clone https://github.com/aplaceforfacts/HRD4WEB.git
cd HRD4WEB
cp .env.example .env # then fill in the values below
npm install # also runs `prisma generate` (client goes to src/generated/)
npx prisma db push # fresh database: builds the schema from prisma/schema.prisma
npm run prisma:seed # creates league `hrd` for the current MLB season
npm run dev
Open http://localhost:3000, then run npm test to check everything works.
The migrations in prisma/migrations/ are incremental changes to a database that already existed, so prisma migrate deploy only works against an existing production database. Use prisma db push for a new one. Prisma 7 no longer loads .env by itself; prisma.config.ts and src/lib/prisma.ts load it through dotenv.
Environment variables
| Variable | Required | Purpose |
|---|
DATABASE_URL | Yes | PostgreSQL connection string |
ADMIN_SECRET | Yes for admin | Password for /admin and Bearer token for scripts. Falls back to CRON_SECRET. Use a long random value. |
CRON_SECRET | Yes in production | Bearer token Vercel Cron sends to the cron routes |
RESEND_API_KEY | For emails | Resend API key for the monthly workbook |
EXPORT_FROM_EMAIL | For emails | Sender, e.g. Home Run Derby <[email protected]> |
PUBLIC_SITE_URL | For emails | Base URL used in email links |
EXPORT_SIGNING_SECRET | Optional | Signs unsubscribe links. Defaults to CRON_SECRET. |
NEXT_PUBLIC_APP_NAME | Optional | Site name shown in the UI |
LEGACY_LEAGUE_SLUG | Optional | League that old unscoped links (/standings, /team/...) redirect to. Defaults to hrd. |
Never commit .env. Only .env.example is tracked.
Scripts
| Command | What it does |
|---|
npm run dev / build / start | Run, build and serve the app |
npm test | Run the Vitest suite |
npm run prisma:migrate / prisma:deploy | Create or apply migrations (existing databases) |
npm run prisma:seed | Seed league hrd |
npm run season:setup | Create a new season for a league |
npm run season:import-workbook | Import players and teams from the host's workbook |
npm run season:export-workbook | Build a standings workbook without emailing it |
npm run sync | Run the nightly scoring pipeline by hand |
npm run import:projections | Load projection CSVs |
npm run backfill:historical-stats | Backfill past seasons' stats |
How it runs in production
vercel.json schedules two Vercel Cron jobs:
| Path | Schedule (UTC) | Job |
|---|
/api/admin/sync/run | 0 9 * * * | Nightly MLB game-log sync, scoring, odds and forecast snapshots |
/api/cron/monthly-export | 0 15 * * * | Sends any monthly workbook that has been closed for two days, and resumes interrupted sends |
Both routes are protected by the proxy and expect Authorization: Bearer <CRON_SECRET>, which Vercel Cron adds automatically.
Running a season
Each year starts fresh: new owners, a new player pool, and the league's format carried over.
# 1. Create the season (pulls opening/closing day from MLB, copies groups and prize sheet)
npx tsx scripts/setup-season.ts hrd 2027
# 2. Load the player pool and teams from the host's workbook (dry run first)
npx tsx scripts/import-host-workbook.ts hrd 2027 "2027 Home Run Derby.xlsx"
npx tsx scripts/import-host-workbook.ts hrd 2027 "2027 Home Run Derby.xlsx" --commit
# 3. Projections and history for the entry form and forecasts
npx tsx scripts/import-projections.ts 2027 path/to/projections.csv
npx tsx scripts/backfill-historical-stats.ts 2025 2026
Then run a sync from /admin/sync, add owner emails on the season's admin page, and open entries. To start a second league:
npx tsx scripts/setup-season.ts office-derby 2027 "Office Home Run Derby"
The full yearly checklist, MLB ID overrides and email setup are in docs/OFFSEASON.md.
Project layout
├── prisma/ # Schema, migrations, seed (prisma.config.ts at the root)
├── scripts/ # Season setup, imports, exports, manual sync
├── docs/ # Offseason guide and yearly checklist
├── src/
│ ├── app/
│ │ ├── [league]/ # Public pages: standings, players, optimal, odds, team, submit, rules
│ │ ├── admin/ # Commissioner area
│ │ └── api/ # admin, cron and public routes
│ ├── components/ # UI, including Arc components
│ ├── lib/ # Admin auth, login throttle, Prisma client, helpers
│ ├── server/ # Entries, scoring, stats sync, odds, forecasts, export, email
│ └── proxy.ts # Gates /admin, /api/admin and /api/cron
└── tests/ # Vitest suites
Security notes
/admin, /api/admin/* and /api/cron/* are gated by the Next.js proxy (src/proxy.ts). Browser sessions use a signed, expiring, httpOnly cookie; scripts and cron use a Bearer secret. Secrets are compared in constant time.- Failed admin sign-ins are throttled per client. The throttle is in-memory, so for a hard limit add a Vercel WAF rate-limit rule on
/api/admin/login.
- Responses include standard security headers (
X-Frame-Options, X-Content-Type-Options, HSTS, and others).
- Public entry and search inputs are length-limited, and unsubscribe links are HMAC-signed.
- Commissioners currently share one admin secret. Per-league logins are a planned next step.
License
No license has been specified yet. Until one is added, all rights are reserved by the author.
