Football Club Widget

A real-time widget for Notion (or any embeddable page) showing matches, standings, position history, and recent form for a football club you pick from a dropdown — any club across 9 domestic leagues in 8 countries, via football-data.org.

📦 What's Included

File	Purpose
server.js	Backend Node.js server — proxies API calls, hides your API key
widget.html	Frontend Notion widget — self-contained, no build step
package.json	Node.js dependencies
.env.example	Environment variables template

🚀 Quick Start

1. Get the project on your PC, then from inside the folder:

   npm install
   

2. Create your .env file:

   cp .env.example .env
   

   Then edit it:

   PORT=3000
   API_KEY=your_football_data_org_api_key_here
   

   (see "API Key & Security" below for how to get one)
3. Start the server:

   npm start
   # or, with auto-reload during development:
   npm run dev
   

   Your server is now running at http://localhost:3000.
4. Open the widget — visit http://localhost:3000/widget, or open widget.html directly in your browser.

🌐 Deploying the Backend

Pick one, then point widget.html's backendUrl constant at it.

• Server runs on http://localhost:3000
• Set const backendUrl = 'http://localhost:3000'; in widget.html
• Only works on your own PC

1. Go to https://replit.com and create an account
2. Create a new Node.js Repl
3. Upload all the project files
4. Click Run
5. Copy your Repl's URL (https://your-replit-name.replit.dev)
6. Set const backendUrl = 'https://your-replit-name.replit.dev'; in widget.html

1. Go to https://vercel.com and connect your GitHub account
2. Import this repository and deploy — Vercel auto-detects Express, no extra config needed
3. In the project's Settings → Environment Variables, add API_KEY (see "API Key & Security" below)
4. Copy your Vercel URL and set it as backendUrl in widget.html, then push to redeploy

Vercel serves the widget page itself too, at <your-vercel-url>/widget — so this is the only option here where you don't need to separately host the frontend. See "Using the Widget" below for embedding that URL directly in Notion instead of copy-pasting HTML.

1. Go to https://heroku.com and create a new app
2. Connect and deploy this repository
3. Copy your Heroku URL and set it as backendUrl in widget.html

📝 Using the Widget

Locally: start the server (npm start), open the widget, and pick a country then a club from the dropdowns.

In Notion, pick one:

• Embed the URL directly (only when the backend also serves the widget page itself, e.g. deployed on Vercel): + Add Block → Embed, then paste <your-vercel-url>/widget. Notion loads it in an iframe — nothing to copy or re-paste after future changes, since it always reflects whatever's currently deployed.
• Upload the HTML file (works with any backend host — pasting the raw HTML into an Embed block does not work in Notion):
  1. Set backendUrl in widget.html to your deployed backend's URL
  2. In Notion, add an HTML block and upload your widget.html file

Either way: pick a club — your choice is remembered in that browser for next time, and the selector hides itself automatically after that (click "Change club" to bring it back)

🔑 API Key & Security

• Get a free key at https://www.football-data.org/client/register
• Put it in your .env file (see .env.example) — it's read only on the backend and never sent to the browser
• .env is gitignored — never commit it or share it publicly
• Safe to embed the widget on private Notion pages

📊 Features

• Pick any club across Premier League, Championship, La Liga, Serie A, Bundesliga, Ligue 1, Eredivisie, Primeira Liga, and Brasileirão
• Last 2 results + next 2 fixtures (opponent, home/away, score or 24h kickoff time)
• A single League section with Table (a 5-team window centered on your club, clamped at the top/bottom of the table), Position progress (color-coded by table zone: title contender / top 4 / mid-table / relegation, with the position number only labeled where it changes), and Form — plus a matching Champions League section when the club is in it this season
• Recent form as a grid of win/draw/loss/upcoming squares
• Club selection remembered per browser (localStorage); the country/club dropdowns can be hidden once you've picked a club (they default to hidden after that) and reopened anytime via the "Change club" link
• A layout picker (⚙ next to "Change club") switches between Scroll (default), Tabs (one section at a time), and Side-by-side (sections as cards in a row, stretching to fill the embed's width and splitting League into a Table card + a Position/Form card) — remembered per browser
• The same ⚙ menu has Sections checkboxes (Matches, League Table, League Position, League Form, UCL Form) to choose which parts of the widget are shown — remembered per browser
• Matches Notion's own default look — same font, and the same light/dark background palette Notion pages use
• Light/dark theme aware, fully responsive — including narrow Notion columns (down to ~240px, e.g. a page split into 3+ columns)

⚽ Available Leagues & Clubs

The exact roster depends on football-data.org's current season data (promotions, relegations, name changes will shift this over time) — this is what's selectable today. Any of these clubs that's also in the Champions League this season gets the extra Champions League section automatically.

🛠️ Troubleshooting

Problem	Fix
"Cannot GET /"	Backend isn't running — run npm start
"Failed to fetch" / "Could not reach the backend"	Check backendUrl in widget.html; make sure the backend is running; check the browser console for errors
Port already in use	Change PORT in .env, or stop whatever else is using it
Data not updating, or the dropdowns stay empty	Check your API key in .env; verify your internet connection; check the browser console
Occasional "Failed to fetch" while switching clubs quickly	Expected — the free football-data.org tier allows only 10 requests/minute. Wait a few seconds and try again

Still stuck? Open the browser console (F12) for detailed error messages.