DEV Community: Miheve

I Built a Football Livescore App That Still Works Without an API Key

Miheve — Sun, 14 Jun 2026 14:34:44 +0000

A football livescore app looks simple until you try to build one properly.

At first, the idea was straightforward:

show live matches
let users browse fixtures by date
organize games by league
add a match details page
display team and competition logos

But once I started building it, the real challenge was not rendering a score.

The harder part was deciding how the data layer should behave when:

the API key is missing
the external API is unavailable
the response shape changes
a team logo does not exist
the UI needs to work before the live integration is ready

That led me to build PitchPulse Live, a production-style football livescore application using Next.js, TypeScript, Tailwind CSS, and SportMicro football data.

The part I like most is that the application does not become unusable when no API key is configured.

It automatically switches to mock data.

This means someone can clone the repository, run the app, explore the interface, and continue development without first setting up access to an external sports API.

Repository:

github.com/mihailove123/pitchpulse-livescore-ap

What I Wanted to Build

I did not want the project to be only a page with several hardcoded match cards.

The goal was to create a small but realistic football product with a structure that could later support more advanced features.

The first version includes:

a live match scoreboard
daily fixture browsing
league filtering
a league directory
individual match pages
team and league logos
server-rendered data fetching
automatic mock fallback

The main routes are:

/               Live matches and daily fixtures
/leagues        Football league directory
/matches/[id]   Match details

The app is built with the Next.js App Router.

That allowed me to keep the initial data fetching on the server while still using interactive client components for date selection and league filtering.

The Stack

The project uses:

Next.js 16
React 19
TypeScript
Tailwind CSS 4
SportMicro Football API
@sportmicro/endpoint

The project structure looks like this:

src/
  app/
    page.tsx
    leagues/
      page.tsx
    matches/
      [id]/
        page.tsx

  components/
    EntityLogo.tsx
    MatchCard.tsx
    MatchList.tsx
    LeagueFilter.tsx
    DateSelector.tsx

  lib/
    sportmicro.ts
    mock-data.ts
    utils.ts

  types/
    sportmicro.ts

public/
  screenshots/
    sc.png

The important design decision was to keep the football data logic separate from the UI.

The pages should not need to know how authentication headers are created, how query parameters are built, or how raw API responses are normalized.

They should only receive app-friendly objects and render them.

The First Problem: External Data Should Not Control the Entire App

When building an API-powered interface, it is tempting to connect the UI directly to the raw response.

For example:

<div>
  <span>{match.home_team?.name}</span>
  <span>{match.score?.home}</span>
  <span>{match.score?.away}</span>
  <span>{match.away_team?.name}</span>
</div>

This works initially, but it creates a tight dependency between the interface and the external API.

If the API changes a field name, every component using that field may need to change.

Instead, PitchPulse normalizes the responses inside the data layer.

The UI consumes internal types such as:

export type FootballMatch = {
  id: string
  homeTeam: {
    id: string
    name: string
    logo?: string
  }
  awayTeam: {
    id: string
    name: string
    logo?: string
  }
  homeScore: number | null
  awayScore: number | null
  status: string
  startTime: string
  league: {
    id: string
    name: string
    logo?: string
  }
}

This creates a useful boundary:

External API response
        ↓
Normalization layer
        ↓
Application types
        ↓
React components

The components no longer care where the data came from.

That becomes especially useful because the same components can render both live API data and local mock data.

Using `@sportmicro/endpoint` as a Query Builder

The project uses the @sportmicro/endpoint package, but not as a full API client.

I use it to construct PostgREST-style endpoint paths.

For example:

const path = endpoint("matches")
  .property("status_type")
  .equals("live")
  .select(
    "id",
    "start_time",
    "status_type",
    "home_team",
    "away_team",
    "home_score",
    "away_score"
  )
  .limit("12")
  .order((order) =>
    order.property("start_time").ascending
  )
  .toString()

The package handles the query structure.

The application still sends the actual HTTP request with fetch.

const response = await fetch(
  `${FOOTBALL_API_URL}/${path}?lang=en`,
  {
    headers: {
      Authorization: `Bearer ${SPORTMICRO_API_KEY}`,
      Accept: "application/json",
    },
    next: {
      revalidate: 30,
    },
  }
)

I like this approach because it keeps endpoint construction readable.

Instead of manually building a long query string:

const url =
  "/matches?status_type=eq.live&select=id,start_time,status_type..."

the code describes the query step by step.

One Wrapper for All Football Requests

The SportMicro integration lives in:

src/lib/sportmicro.ts

That file is responsible for:

building endpoint paths
attaching the API key
sending requests
handling errors
switching to mock data
normalizing responses

The rest of the application calls functions such as:

getLiveFootballMatches()
getFixturesByDate(date)
getMatchDetails(matchId)
getLeagues()

A page does not need to know which endpoint is being used.

export default async function HomePage() {
  const liveMatches =
    await getLiveFootballMatches()

  const fixtures =
    await getFixturesByDate(today)

  return (
    <main>
      <MatchList matches={liveMatches} />
      <MatchList matches={fixtures} />
    </main>
  )
}

This keeps the page focused on presentation.

The transport logic remains in one place.

Why I Added Mock Mode

The mock fallback became one of the most useful parts of the project.

Normally, an API-powered repository creates friction for anyone trying to run it.

They clone the project, install the dependencies, and immediately see an error:

Missing API key

That is not a great first experience.

In PitchPulse Live, the application checks whether the environment variable exists.

const apiKey = process.env.SPORTMICRO_API_KEY

const isMockMode = !apiKey

When the key is missing, the data functions return local sample data.

export async function getLiveFootballMatches() {
  if (isMockMode) {
    return mockLiveMatches
  }

  return fetchLiveMatchesFromApi()
}

That means the setup can be as simple as:

git clone https://github.com/mihailove123/pitchpulse-livescore-ap.git

cd pitchpulse-livescore-ap

npm install

npm run dev

No external account is required to inspect the layout.

No secret needs to be configured to work on the components.

The live integration can be enabled later by creating .env.local:

SPORTMICRO_API_KEY=your_sportmicro_api_key_here

This creates two useful development modes.

Mock mode
  UI development
  component testing
  layout work
  demos
  local onboarding

Live mode
  real scores
  real fixtures
  real leagues
  real match details

The same UI works in both modes because both data sources are normalized into the same types.

Making Missing Logos Look Intentional

Football data is rarely perfectly complete.

Some teams have logos.

Some do not.

Some image URLs fail.

Some lower-level leagues may have incomplete branding.

Rendering a broken image icon makes the whole application look unfinished.

That is why I added a reusable EntityLogo component.

type EntityLogoProps = {
  name: string
  imageUrl?: string | null
}

export function EntityLogo({
  name,
  imageUrl,
}: EntityLogoProps) {
  if (imageUrl) {
    return (
      <img
        src={imageUrl}
        alt={`${name} logo`}
        className="h-10 w-10 object-contain"
      />
    )
  }

  const initials = name
    .split(" ")
    .map((word) => word[0])
    .join("")
    .slice(0, 2)
    .toUpperCase()

  return (
    <div className="flex h-10 w-10 items-center justify-center rounded-full bg-neutral-800 text-sm font-semibold">
      {initials}
    </div>
  )
}

Remote images are loaded from:

https://images.sportmicro.com/{hash}.png

If no valid image is available, the component displays initials instead.

This is a small feature, but it prevents incomplete data from damaging the interface.

The fallback looks intentional rather than accidental.

Building Reusable Match Cards

The main reusable UI unit is MatchCard.tsx.

A match card needs to support several states:

Scheduled
Live
Finished
Postponed
Cancelled

A scheduled match should emphasize kickoff time.

A live match should emphasize the score and current status.

A completed match should make it clear that the score is final.

A simplified version looks like this:

export function MatchCard({
  match,
}: {
  match: FootballMatch
}) {
  const isScheduled =
    match.status === "scheduled"

  const isLive =
    match.status === "live"

  return (
    <article className="rounded-xl border p-4">
      <div className="flex items-center justify-between">
        <Team
          name={match.homeTeam.name}
          logo={match.homeTeam.logo}
        />

        <div className="text-center">
          {isScheduled ? (
            <time dateTime={match.startTime}>
              {formatMatchTime(match.startTime)}
            </time>
          ) : (
            <strong className="text-xl">
              {match.homeScore ?? 0}
              {" - "}
              {match.awayScore ?? 0}
            </strong>
          )}

          {isLive && (
            <span className="block text-xs">
              LIVE
            </span>
          )}
        </div>

        <Team
          name={match.awayTeam.name}
          logo={match.awayTeam.logo}
        />
      </div>
    </article>
  )
}

Because the card consumes normalized match data, it can be reused on:

the homepage
fixture results
league pages
related-match sections
search results

Date and League Filtering

The homepage includes controls for browsing fixtures.

The user can select a date and narrow the list by league.

The date selector updates the requested day:

<DateSelector selectedDate={date} />

The league filter receives the competitions found in the returned fixtures:

<LeagueFilter
  leagues={availableLeagues}
  selectedLeague={leagueId}
/>

The filtering logic stays separate from the match card.

That separation matters because the match component should not decide which matches are visible.

Its job is only to render one match correctly.

Match Details as a Dynamic Route

Each match links to:

/matches/[id]

The page reads the dynamic route parameter and loads the details.

type MatchPageProps = {
  params: Promise<{
    id: string
  }>
}

export default async function MatchPage({
  params,
}: MatchPageProps) {
  const { id } = await params

  const match =
    await getMatchDetails(id)

  return (
    <main>
      <MatchHeader match={match} />
      <MatchSummary match={match} />
    </main>
  )
}

The current page displays a score snapshot and match summary.

The route is intentionally designed so it can later support:

incidents
goals
cards
substitutions
lineups
statistics
head-to-head results

That is one of the advantages of starting with a clear route and data layer rather than placing everything on one page.

Server Rendering Keeps the Pages Simple

The application uses server-rendered data fetching.

This means pages can request their data before rendering.

export default async function LeaguesPage() {
  const leagues = await getLeagues()

  return (
    <main>
      <h1>Football Leagues</h1>
      <LeagueGrid leagues={leagues} />
    </main>
  )
}

There is no initial client-side loading effect.

There is no empty page waiting for JavaScript to fetch the first result.

Interactive pieces such as the date selector can still be client components, but the initial football data is rendered on the server.

This gives the project a clean split:

Server Components
  data fetching
  page composition
  initial rendering

Client Components
  filters
  date controls
  interactive state

The Complete Data Flow

A typical request moves through the project like this:

User opens the homepage
        ↓
Next.js page calls getLiveFootballMatches()
        ↓
The helper checks for SPORTMICRO_API_KEY
        ↓
No key?
  Return normalized mock data
        ↓
Key exists?
  Build the API path with @sportmicro/endpoint
        ↓
Send the authenticated request with fetch
        ↓
Normalize the response
        ↓
Render MatchList
        ↓
MatchList renders MatchCard components

The UI never needs separate code for live and mock mode.

That is the main benefit of normalizing the data before it reaches the components.

Running the Project

Clone the repository:

git clone https://github.com/mihailove123/pitchpulse-livescore-ap.git

Enter the project:

cd pitchpulse-livescore-ap

Install dependencies:

npm install

Run the development server:

npm run dev

Open:

http://localhost:3000

The application will automatically run with sample data.

To enable live football data, create:

.env.local

Add:

SPORTMICRO_API_KEY=your_sportmicro_api_key_here

Then restart the development server.

Available Commands

npm run dev
npm run build
npm run start
npm run lint
npm run typecheck

Before deploying, I recommend running:

npm run lint
npm run typecheck
npm run build

This catches type errors and production build issues before they reach the hosting platform.

Deployment

The repository can be deployed to Vercel or another Next.js-compatible platform.

A basic deployment flow is:

Push the repository to GitHub
        ↓
Import the repository into Vercel
        ↓
Add SPORTMICRO_API_KEY
        ↓
Deploy

Mock mode can also be useful for preview deployments where live credentials should not be available.

What I Would Build Next

The current repository provides a foundation rather than every possible football feature.

The next additions could include:

league standings
match incidents
team lineups
player statistics
team pages
league-specific fixture pages
favorite teams
goal notifications
live polling
match search
user time zones

The existing structure makes these additions easier because the transport and UI layers are already separated.

New API methods can be added to:

src/lib/sportmicro.ts

New normalized types can be added to:

src/types/sportmicro.ts

The components can continue receiving predictable application objects.

What I Learned

The most important lesson from this project was not about football data.

It was about fallback design.

An API integration should not make the entire application impossible to run without the API.

By keeping mock and live data behind the same functions, the project becomes:

easier to clone
easier to test
easier to demonstrate
easier to contribute to
easier to develop offline

The second lesson was to normalize external data early.

Raw API responses are useful at the network boundary.

They should not become the language spoken by the entire application.

The final architecture is simple:

Query builder
      ↓
Authenticated request
      ↓
Normalized application data
      ↓
Reusable football components

That structure is what turns a football API demo into an application that can continue growing.

The source code is available here:

PitchPulse Live on GitHub

I would be interested to hear how other developers handle mock mode in API-powered projects. Do you keep static fixtures, use a local mock server, or make the real integration optional?

My Football App Worked Perfectly Until Matchday Started

Miheve — Sun, 14 Jun 2026 14:17:09 +0000

Building a football scores app looked easy when I first planned it.

Fetch today's matches.

Display the teams.

Show the score.

Refresh the page every few seconds.

That was the entire architecture.

During development, it worked perfectly. I tested it with a few sample matches, opened the page in two browser tabs, and watched the scores update.

Then the first busy matchday arrived.

Several games started at the same time. Hundreds of users opened the app. Requests began overlapping. Some scores appeared to move backward. Finished matches continued refreshing, and the same football data was fetched separately for every visitor.

The API was working correctly.

The frontend was rendering what it received.

The problem was everything between them.

That day taught me that a football livescore app is not simply a website connected to an API.

It is a live data synchronization system.

The First Version

My first implementation was a client-side component with a polling interval.

"use client"

import { useEffect, useState } from "react"

type Match = {
  id: string
  homeTeam: string
  awayTeam: string
  homeScore: number
  awayScore: number
}

export default function LiveMatches() {
  const [matches, setMatches] = useState<Match[]>([])

  useEffect(() => {
    async function fetchMatches() {
      const response = await fetch("/api/matches/live")
      const data = await response.json()

      setMatches(data.matches)
    }

    fetchMatches()

    const intervalId = window.setInterval(
      fetchMatches,
      5000
    )

    return () => {
      window.clearInterval(intervalId)
    }
  }, [])

  return (
    <div>
      {matches.map((match) => (
        <article key={match.id}>
          <span>{match.homeTeam}</span>

          <strong>
            {match.homeScore} - {match.awayScore}
          </strong>

          <span>{match.awayTeam}</span>
        </article>
      ))}
    </div>
  )
}

It looked reasonable.

Every five seconds, the app requested the newest scores and replaced the current state.

The problem became obvious when the number of users increased.

1 user      = 12 requests per minute
100 users   = 1,200 requests per minute
1,000 users = 12,000 requests per minute

Most of those requests were asking for exactly the same data.

Every browser was independently fetching the same matches.

The app had no shared cache, no request coordination, and no understanding of whether the matches could still change.

A Live Score Does Not Need to Be Fetched Separately for Every User

When two users open the same match page, they usually need the same score.

The score is not personalized.

That means the server should be able to reuse a recently fetched result instead of requesting the football provider again for every visitor.

A basic server-side request function might look like this:

// lib/football-api.ts

import "server-only"

const baseUrl = process.env.FOOTBALL_API_URL
const apiKey = process.env.FOOTBALL_API_KEY

if (!baseUrl) {
  throw new Error("FOOTBALL_API_URL is missing")
}

if (!apiKey) {
  throw new Error("FOOTBALL_API_KEY is missing")
}

export async function footballRequest<T>(
  endpoint: string,
  revalidate = 15
): Promise<T> {
  const response = await fetch(
    `${baseUrl}${endpoint}`,
    {
      headers: {
        Accept: "application/json",
        Authorization: `Bearer ${apiKey}`,
      },
      next: {
        revalidate,
      },
    }
  )

  if (!response.ok) {
    throw new Error(
      `Football API request failed with ${response.status}`
    )
  }

  return response.json() as Promise<T>
}

The important part is not the exact URL or authentication format.

The important part is that the external API request happens on the server.

The browser communicates with your application.

Your application communicates with the football data provider.

This gives you control over:

API credentials
Caching
Error handling
Rate limiting
Response formatting
Logging

Never Expose the Football API Key in the Browser

This is unsafe:

const response = await fetch(
  `https://example.com/live?key=${process.env.NEXT_PUBLIC_FOOTBALL_API_KEY}`
)

Variables prefixed with NEXT_PUBLIC_ can be included in client-side JavaScript.

Anyone using the application may be able to inspect the request and copy the key.

Instead, keep the key in a private environment variable:

FOOTBALL_API_URL=https://api.example.com
FOOTBALL_API_KEY=your_private_key

Then import the API client only from server-side files.

import "server-only"

A football app can generate a large number of requests during popular matches. An exposed key can quickly become expensive.

Do Not Use the Raw API Response Everywhere

My next mistake was passing the provider response directly into React components.

The component expected fields such as:

<p>{event.home_team.name}</p>
<p>{event.current_score.home}</p>
<p>{event.match_status}</p>

That created a strong dependency between the UI and one specific response format.

When one endpoint returned homeTeam instead of home_team, I had to add special cases inside the component.

A better approach is to define an internal match type.

// types/match.ts

export type MatchStatus =
  | "scheduled"
  | "live"
  | "halftime"
  | "finished"
  | "postponed"
  | "cancelled"

export type Team = {
  id: string
  name: string
  logoUrl: string | null
}

export type FootballMatch = {
  id: string
  competition: {
    id: string
    name: string
    country: string | null
  }
  homeTeam: Team
  awayTeam: Team
  score: {
    home: number | null
    away: number | null
  }
  status: MatchStatus
  minute: number | null
  startsAt: string
}

Then map the provider response into the application's format.

// lib/map-match.ts

import type {
  FootballMatch,
  MatchStatus,
} from "@/types/match"

type ApiMatch = {
  id: string | number
  status?: string
  minute?: number | null
  start_time?: string
  league?: {
    id?: string | number
    name?: string
    country?: string
  }
  home?: {
    id?: string | number
    name?: string
    logo?: string
  }
  away?: {
    id?: string | number
    name?: string
    logo?: string
  }
  scores?: {
    home?: number | null
    away?: number | null
  }
}

export function mapMatch(
  match: ApiMatch
): FootballMatch {
  return {
    id: String(match.id),
    competition: {
      id: String(match.league?.id ?? "unknown"),
      name: match.league?.name ?? "Unknown competition",
      country: match.league?.country ?? null,
    },
    homeTeam: {
      id: String(match.home?.id ?? "unknown-home"),
      name: match.home?.name ?? "Home team",
      logoUrl: match.home?.logo ?? null,
    },
    awayTeam: {
      id: String(match.away?.id ?? "unknown-away"),
      name: match.away?.name ?? "Away team",
      logoUrl: match.away?.logo ?? null,
    },
    score: {
      home: match.scores?.home ?? null,
      away: match.scores?.away ?? null,
    },
    status: normalizeStatus(match.status),
    minute: match.minute ?? null,
    startsAt:
      match.start_time ?? new Date().toISOString(),
  }
}

function normalizeStatus(
  status?: string
): MatchStatus {
  switch (status?.toLowerCase()) {
    case "live":
    case "first_half":
    case "second_half":
    case "in_progress":
      return "live"

    case "half_time":
    case "halftime":
      return "halftime"

    case "full_time":
    case "finished":
    case "ended":
      return "finished"

    case "postponed":
      return "postponed"

    case "cancelled":
    case "canceled":
      return "cancelled"

    default:
      return "scheduled"
  }
}

Now the components depend on a stable application model.

If the external API changes, only the mapping layer needs to change.

Render the First Match List on the Server

My first app displayed an empty loading screen until the browser completed its first request.

That was unnecessary.

With Next.js Server Components, the initial matches can be loaded before the page reaches the browser.

// app/page.tsx

import { MatchCenter } from "@/components/match-center"
import { getMatchesByDate } from "@/lib/get-matches"

export default async function HomePage() {
  const date = new Date()
    .toISOString()
    .slice(0, 10)

  const matches = await getMatchesByDate(date)

  return (
    <main>
      <header>
        <p>Football scores</p>
        <h1>Today's Matches</h1>
      </header>

      <MatchCenter
        date={date}
        initialMatches={matches}
      />
    </main>
  )
}

The server-side data function can apply a short cache duration.

// lib/get-matches.ts

import "server-only"

import { footballRequest } from "@/lib/football-api"
import { mapMatch } from "@/lib/map-match"
import type { FootballMatch } from "@/types/match"

type MatchesResponse = {
  matches: unknown[]
}

export async function getMatchesByDate(
  date: string
): Promise<FootballMatch[]> {
  const response =
    await footballRequest<MatchesResponse>(
      `/matches?date=${encodeURIComponent(date)}`,
      30
    )

  return response.matches.map((match) =>
    mapMatch(match as never)
  )
}

The visitor sees content immediately.

The client-side code only needs to keep that content updated.

Use Your Own Route Handler for Updates

The browser should not need to know which provider powers the football data.

Create an internal endpoint.

// app/api/matches/route.ts

import { NextRequest, NextResponse } from "next/server"
import { getMatchesByDate } from "@/lib/get-matches"

export async function GET(
  request: NextRequest
) {
  const date =
    request.nextUrl.searchParams.get("date")

  if (!date || !isValidDate(date)) {
    return NextResponse.json(
      {
        error:
          "A valid date in YYYY-MM-DD format is required",
      },
      {
        status: 400,
      }
    )
  }

  try {
    const matches = await getMatchesByDate(date)

    return NextResponse.json(
      {
        matches,
        updatedAt: new Date().toISOString(),
      },
      {
        headers: {
          "Cache-Control":
            "public, s-maxage=10, stale-while-revalidate=20",
        },
      }
    )
  } catch (error) {
    console.error(
      "Failed to load football matches",
      error
    )

    return NextResponse.json(
      {
        error:
          "Football data is temporarily unavailable",
      },
      {
        status: 503,
      }
    )
  }
}

function isValidDate(value: string): boolean {
  return /^\d{4}-\d{2}-\d{2}$/.test(value)
}

This endpoint becomes the boundary between the browser and the football provider.

Later, you can add:

Rate limiting
Authentication
Analytics
Provider fallback
Region-specific caching
Subscription checks
Request tracing

Stop Polling When Nothing Is Live

This was the easiest improvement and one of the most valuable.

My original app refreshed the match list every five seconds, even when every match was finished.

A finished score is unlikely to change.

A match scheduled for tomorrow does not need to be requested every few seconds.

The polling logic should depend on the match state.

// components/match-center.tsx

"use client"

import {
  useCallback,
  useEffect,
  useRef,
  useState,
} from "react"

import type { FootballMatch } from "@/types/match"
import { MatchList } from "@/components/match-list"

type MatchCenterProps = {
  date: string
  initialMatches: FootballMatch[]
}

export function MatchCenter({
  date,
  initialMatches,
}: MatchCenterProps) {
  const [matches, setMatches] =
    useState(initialMatches)

  const [lastUpdated, setLastUpdated] =
    useState<string | null>(null)

  const [error, setError] =
    useState<string | null>(null)

  const currentRequest =
    useRef<AbortController | null>(null)

  const hasLiveMatches = matches.some(
    (match) =>
      match.status === "live" ||
      match.status === "halftime"
  )

  const refreshMatches = useCallback(
    async () => {
      currentRequest.current?.abort()

      const controller = new AbortController()
      currentRequest.current = controller

      try {
        const response = await fetch(
          `/api/matches?date=${encodeURIComponent(date)}`,
          {
            cache: "no-store",
            signal: controller.signal,
          }
        )

        if (!response.ok) {
          throw new Error(
            `Request failed with ${response.status}`
          )
        }

        const data = await response.json()

        setMatches(data.matches)
        setLastUpdated(data.updatedAt)
        setError(null)
      } catch (error) {
        if (
          error instanceof DOMException &&
          error.name === "AbortError"
        ) {
          return
        }

        console.error(error)

        setError(
          "Live updates are temporarily delayed."
        )
      }
    },
    [date]
  )

  useEffect(() => {
    if (!hasLiveMatches) {
      return
    }

    const intervalId = window.setInterval(
      refreshMatches,
      15_000
    )

    return () => {
      window.clearInterval(intervalId)
      currentRequest.current?.abort()
    }
  }, [hasLiveMatches, refreshMatches])

  return (
    <section>
      {lastUpdated && (
        <small>
          Updated{" "}
          {new Date(
            lastUpdated
          ).toLocaleTimeString()}
        </small>
      )}

      {error && (
        <p role="status">{error}</p>
      )}

      <MatchList matches={matches} />
    </section>
  )
}

The important check is:

if (!hasLiveMatches) {
  return
}

When no match is live, the refresh interval is not created.

Old Requests Can Overwrite New Scores

Polling introduces a race condition that is easy to miss.

Imagine these two requests:

Request A starts at 14:30:00
Request B starts at 14:30:15

Request B returns first with a score of 2-1
Request A returns later with a score of 1-1

If both responses update the same state, the app shows the older score after the newer one.

From the user's perspective, the score moves backward.

This does not necessarily mean the football API returned incorrect data.

It may mean the responses arrived in the wrong order.

That is why the component aborts the previous request before starting a new one.

currentRequest.current?.abort()

const controller = new AbortController()
currentRequest.current = controller

The older request is no longer allowed to overwrite the newest result.

Do Not Delete Good Data Because One Refresh Failed

My first error handler replaced the match list with an empty array.

That was a bad decision.

A score that is fifteen seconds old is usually more useful than no score at all.

When a background refresh fails, keep the last successful data visible.

try {
  const latestMatches = await loadMatches()

  setMatches(latestMatches)
  setError(null)
} catch {
  setError(
    "Updates are delayed. Showing the latest available scores."
  )
}

The UI should communicate that the data may be stale, but it should not destroy useful information.

A live football app has more states than just loading, success, and error.

Initial loading
Fresh data
Refreshing
Temporarily stale data
Partial data
Provider unavailable
Recovered

Designing for these states makes the app feel much more stable.

Match Status Should Control Behavior

At first, I treated match status as a label.

<span>{match.status}</span>

But status is not only presentation data.

It should control the application.

For example:

// lib/match-status.ts

import type { FootballMatch } from "@/types/match"

export function isLive(
  match: FootballMatch
): boolean {
  return (
    match.status === "live" ||
    match.status === "halftime"
  )
}

export function isFinished(
  match: FootballMatch
): boolean {
  return match.status === "finished"
}

export function canStillChange(
  match: FootballMatch
): boolean {
  return (
    match.status === "scheduled" ||
    match.status === "live" ||
    match.status === "halftime"
  )
}

These helpers can determine:

Whether polling should continue
Whether the minute should be shown
Whether kickoff time should be displayed
Whether the score is final
Whether notifications can still be triggered
Whether standings may need updating

As the app grows, you may need additional states such as:

Extra time
Penalties
Interrupted
Abandoned
Delayed
Awarded

Normalizing those states early prevents status checks from spreading throughout the codebase.

Group Matches by Competition

A flat list works when there are five matches.

It becomes difficult to read when there are fifty.

Group the matches by league or competition before rendering them.

// lib/group-matches.ts

import type { FootballMatch } from "@/types/match"

type CompetitionGroup = {
  id: string
  name: string
  country: string | null
  matches: FootballMatch[]
}

export function groupMatchesByCompetition(
  matches: FootballMatch[]
): CompetitionGroup[] {
  const groups = new Map<
    string,
    CompetitionGroup
  >()

  for (const match of matches) {
    const competitionId =
      match.competition.id

    const existing =
      groups.get(competitionId)

    if (existing) {
      existing.matches.push(match)
      continue
    }

    groups.set(competitionId, {
      id: competitionId,
      name: match.competition.name,
      country: match.competition.country,
      matches: [match],
    })
  }

  return Array.from(groups.values())
}

Then render each competition separately.

// components/match-list.tsx

import { groupMatchesByCompetition } from "@/lib/group-matches"
import type { FootballMatch } from "@/types/match"
import { MatchRow } from "@/components/match-row"

type MatchListProps = {
  matches: FootballMatch[]
}

export function MatchList({
  matches,
}: MatchListProps) {
  const groups =
    groupMatchesByCompetition(matches)

  if (groups.length === 0) {
    return (
      <p>No matches are available.</p>
    )
  }

  return (
    <div>
      {groups.map((group) => (
        <section key={group.id}>
          <header>
            {group.country && (
              <span>{group.country}</span>
            )}

            <h2>{group.name}</h2>
          </header>

          <div>
            {group.matches.map((match) => (
              <MatchRow
                key={match.id}
                match={match}
              />
            ))}
          </div>
        </section>
      ))}
    </div>
  )
}

The data structure now supports the interface instead of forcing every component to repeat the same transformation.

A Simple Match Row

Once the data is normalized, the UI becomes much easier to write.

// components/match-row.tsx

import type { FootballMatch } from "@/types/match"
import { isLive } from "@/lib/match-status"

type MatchRowProps = {
  match: FootballMatch
}

export function MatchRow({
  match,
}: MatchRowProps) {
  return (
    <article>
      <div>
        <span>{match.homeTeam.name}</span>

        {match.homeTeam.logoUrl && (
          <img
            src={match.homeTeam.logoUrl}
            alt=""
            width={24}
            height={24}
          />
        )}
      </div>

      <div>
        {match.status === "scheduled" ? (
          <time dateTime={match.startsAt}>
            {new Date(
              match.startsAt
            ).toLocaleTimeString([], {
              hour: "2-digit",
              minute: "2-digit",
            })}
          </time>
        ) : (
          <strong>
            {match.score.home ?? 0}
            {" - "}
            {match.score.away ?? 0}
          </strong>
        )}

        {isLive(match) && (
          <span>
            {match.minute
              ? `${match.minute}'`
              : "LIVE"}
          </span>
        )}
      </div>

      <div>
        {match.awayTeam.logoUrl && (
          <img
            src={match.awayTeam.logoUrl}
            alt=""
            width={24}
            height={24}
          />
        )}

        <span>{match.awayTeam.name}</span>
      </div>
    </article>
  )
}

The component does not know anything about the external provider.

It only understands the application's FootballMatch type.

Caching Does Not Mean Showing Old Scores for Minutes

Developers sometimes avoid caching live data because they assume a cache will make the app feel outdated.

That depends on the cache duration.

A short shared cache can reduce duplicate requests without creating a noticeable delay.

For example:

Browser refresh interval:       15 seconds
Server cache duration:          10 seconds
Stale-while-revalidate window:  20 seconds

Users still receive frequent updates.

But if hundreds of users request the same match data within a short period, the server can reuse the result.

Without shared caching:

500 users
500 external API requests

With a short server cache:

500 users
A much smaller number of external API requests

Live does not always mean uncached.

It often means briefly cached and frequently refreshed.

The Final Request Flow

After restructuring the application, one visit follows this flow:

User opens the football app

Server Component
  Fetches today's matches
  Uses a short shared cache
  Maps the provider response
  Renders the initial page

Browser
  Displays matches immediately
  Checks whether any match is live

If a match is live
  Starts a refresh interval
  Requests updates from the internal API route

Route Handler
  Validates the date
  Reuses recent shared data when possible
  Calls the football provider when needed
  Returns normalized match objects

Client Component
  Cancels the previous request
  Applies the newest result
  Keeps old data if refreshing fails
  Stops polling when all matches finish

Every layer now has a clear responsibility.

The Mental Model That Helped Me

The football provider supplies the raw data.

The server protects, caches, validates, and normalizes it.

The browser renders the data and requests updates only while they are useful.

That is the architecture I wish I had used from the beginning.

My first version was not wrong because it used polling.

It was wrong because polling was the entire architecture.

There was no protection against duplicate requests, stale responses, race conditions, provider changes, or finished matches that could no longer change.

What I Would Add Next

Once the live match flow is stable, the same foundation can support:

Match detail pages
Goals, cards, and substitutions
Starting lineups
League standings
Team pages
Player statistics
Favorite teams
Goal notifications
Match search
User time zones
WebSocket updates
Server-Sent Events
Multiple sports

The important part is keeping the same data flow:

External provider
  ↓
Server-side client
  ↓
Mapping layer
  ↓
Application data functions
  ↓
Route Handler or Server Component
  ↓
User interface

When these boundaries remain clear, adding new football features becomes much easier.

Final Lesson

The visible part of a football app is simple.

Two teams.

One score.

One match clock.

The difficult part is making sure every user sees the newest correct version without generating unnecessary requests or exposing private credentials.

A demo only needs to display football data.

A real football product needs to manage:

Live updates
Shared caching
Request ordering
Match states
Provider failures
Stale data
API security
Response normalization
Rendering performance

My app worked perfectly before matchday because it had never experienced matchday conditions.

The busy afternoon did not break the application.

It revealed the application I had actually built.

Have you ever built a live sports app? What was the first problem that only appeared after real users arrived?

DEV Community: Miheve

I Built a Football Livescore App That Still Works Without an API Key

What I Wanted to Build

The Stack

The First Problem: External Data Should Not Control the Entire App

Using @sportmicro/endpoint as a Query Builder

One Wrapper for All Football Requests

Why I Added Mock Mode

Making Missing Logos Look Intentional

Building Reusable Match Cards

Date and League Filtering

Match Details as a Dynamic Route

Server Rendering Keeps the Pages Simple

The Complete Data Flow

Running the Project

Available Commands

Deployment

What I Would Build Next

What I Learned

My Football App Worked Perfectly Until Matchday Started

The First Version

A Live Score Does Not Need to Be Fetched Separately for Every User

Never Expose the Football API Key in the Browser

Do Not Use the Raw API Response Everywhere

Render the First Match List on the Server

Use Your Own Route Handler for Updates

Stop Polling When Nothing Is Live

Old Requests Can Overwrite New Scores

Do Not Delete Good Data Because One Refresh Failed

Match Status Should Control Behavior

Group Matches by Competition

A Simple Match Row

Caching Does Not Mean Showing Old Scores for Minutes

The Final Request Flow

The Mental Model That Helped Me

What I Would Add Next

Final Lesson

Using `@sportmicro/endpoint` as a Query Builder