WC26 — World Cup 2026 Live Dashboard

A modern, broadcast-style single-page dashboard for the 2026 World Cup: live match spotlight, latest results, tournament stats, group standings, and upcoming fixtures. Real data via API-Football, hosted on Vercel. No accounts, no payments, no email.

Built with Next.js (App Router), Three.js (particle hero), and GSAP (intro motion).

---

How the data works

The browser never talks to API-Football directly — your key would leak. Instead:

browser ──▶ /api/* route handler (server) ──▶ API-Football
                     │
                     ├─ Next.js data cache (revalidate per route)
                     └─ fallback chain: live ▸ last-good cache ▸ dummy

• The API key lives only in server env (API_FOOTBALL_KEY) and is never sent to the client.
• Each route caches upstream responses, so visitor traffic does not map 1:1 to API calls.
• Every payload is tagged source: "live" | "cache" | "dummy"; the live card shows a small badge.
• If the API errors, rate-limits, or has no data yet (pre-tournament), the page falls back to the last good response, then to bundled dummy data — so it never looks broken.

Routes & cache windows

Route	Data	Revalidate	Client poll
/api/live	live match + in-match stats (or next fixture pre-match)	30s	45s
/api/scores	latest results	60s	60s
/api/scorers	top scorers + aggregate stats	1h	120s
/api/standings	group tables	1h	5m
/api/knockout	elimination bracket (Round of 32 → Final)	5m	2m
/api/fixtures	upcoming fixtures	30m	once
/api/match/[id]	per-fixture detail: statistics + events + lineups (on expand)	60s	on expand; 30s while live
/api/predictions	today's prediction ticket (GET) / submit picks (POST)	dynamic; upstream fetch 60s	60s
/api/predictions/leaderboard	prediction league standings (settles finished matches lazily on read)	dynamic; upstream fetch 60s	120s

Competition is fixed to the World Cup via env (WC_LEAGUE=1, WC_SEASON=2026).

Score predictions

A no-login community game: pick exact scores for today's (ET) matches before each kick-off, submit under a callsign, climb the leaderboard — 3 pts for the exact score, 1 pt for the right outcome. Callsigns are soft-claimed by a device token in localStorage (no accounts). Storage is Postgres (Neon via the Vercel Marketplace integration, which provisions DATABASE_URL; POSTGRES_URL is accepted too); without it the game transparently runs on an in-process memory store — fine locally, volatile in production. The schema is created automatically on first use (lib/predictions/db.ts). Settlement is lazy: the first leaderboard read after a final whistle scores that match under a Postgres lock, so no cron is needed.

---

Local development

npm install
cp .env.example .env.local   # then add your API-Football key
npm run dev                  # http://localhost:3000

Get a key at https://dashboard.api-football.com (api-sports.io direct). The header used is x-apisports-key. A free plan works but historically restricts current seasons — a Pro plan covers live season=2026.

.env.local:

API_FOOTBALL_KEY=your_key_here
API_FOOTBALL_HOST=https://v3.football.api-sports.io
WC_LEAGUE=1
WC_SEASON=2026
# Optional — the prediction game/chat persist here; omit to use a volatile memory store:
# DATABASE_URL=postgres://wc26:wc26@localhost:5432/wc26

For a local Postgres to back the prediction game, the quickest is Docker:

docker run -d --name wc26-pg -e POSTGRES_USER=wc26 -e POSTGRES_PASSWORD=wc26 \
  -e POSTGRES_DB=wc26 -p 5432:5432 postgres:16-alpine

Then set DATABASE_URL as above. Tables are created automatically on first request.

---

Deploy to Vercel

npm i -g vercel
vercel            # link + preview deploy
vercel --prod     # production

Then add the same four env vars in Vercel → Project → Settings → Environment Variables (or vercel env add API_FOOTBALL_KEY). Redeploy so the functions pick them up.

No vercel.json needed — Next.js is auto-detected. The /api/* routes run as Vercel Functions.

Security: never commit .env.local. It's gitignored. If a key is ever exposed, rotate it from the API-Football dashboard.

---

Project structure

app/
  layout.tsx            fonts, metadata
  page.tsx              section composition
  globals.css           full design system
  icon.svg              favicon
  api/{live,scores,scorers,standings,knockout,fixtures}/route.ts
  api/predictions/{route,leaderboard/route}.ts   prediction game (GET/POST + board)
components/
  Hero.tsx              Three.js particle football + GSAP title
  LiveCard, Results, Pulse, Groups, Knockout, Fixtures   live, polling sections
  Predictions, PredictionTicket, PredictionLeague   score-prediction game
  Nav, Ticker, Crest, Bar, CountUp, Reveal, useEndpoint, flag
lib/
  apiFootball.ts        upstream client + fallback wrapper (key stays here)
  normalize.ts          raw API → clean UI types
  dummy.ts              fallback data (same shapes)
  types.ts              shared types
  predictions/          game rules (pure) + Postgres/memory store (store.ts, db.ts)

Accessibility & motion

Respects prefers-reduced-motion: disables the particle animation, grain, ticker marquee, reveal transitions, and count-ups; numbers and bars render at final value instantly.

---

Dummy/demo data and team branding are for concept purposes only. Not affiliated with FIFA.