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
- Get the project on your PC, then from inside the folder:
npm install
- 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)
- Start the server:
npm start
# or, with auto-reload during development:
npm run dev
Your server is now running at http://localhost:3000.
- 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
- Go to https://replit.com and create an account
- Create a new Node.js Repl
- Upload all the project files
- Click Run
- Copy your Repl's URL (
https://your-replit-name.replit.dev)
- Set
const backendUrl = 'https://your-replit-name.replit.dev'; in widget.html
- Go to https://vercel.com and connect your GitHub account
- Import this repository and deploy — Vercel auto-detects Express, no extra config needed
- In the project's Settings → Environment Variables, add
API_KEY (see "API Key & Security" below)
- 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.
- Go to https://heroku.com and create a new app
- Connect and deploy this repository
- 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):
- Set
backendUrl in widget.html to your deployed backend's URL
- 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.
