Eclipse mechanics for programmers: turning ephemeris data into a "next eclipse from here" countdown

"When's the next eclipse visible from here?" sounds like a lookup. It's actually two hard problems stacked on top of each other: predicting when an eclipse happens, and predicting whether it's visible from one specific point on Earth. The total solar eclipse crossing Spain on 12 August 2026 — the first over the Spanish mainland in over a century — is a perfect worked example, so I'll use it throughout.

This is a write-up of how we built the prediction and countdown logic behind a small eclipse tracker. No framework lock-in; the ideas port to any language.

1. Where eclipse predictions actually come from

You do not compute eclipses from scratch in a web app. The orbital mechanics (lunar position to arc-second precision, Besselian elements) are solved problems, and re-deriving them in JavaScript is how you ship a tracker that's quietly wrong.

Instead you consume a canon — a precomputed catalog of eclipses with their circumstances. NASA's Five Millennium Canon of Solar Eclipses is the reference dataset; for each event it gives the instant of greatest eclipse (in Terrestrial Time), the magnitude, and the Besselian elements that let you reconstruct the shadow's geometry.

The pragmatic move: bake the events you care about into a static JSON file at build time.

{
  "id": "2026-08-12-total-solar",
  "type": "total",
  "peakUTC": "2026-08-12T18:46:13Z",
  "magnitude": 1.039,
  "centralPath": "2026-08-12-path.geojson"
}

Now the runtime never does ephemeris math. It does timezone conversion and a point-in-polygon test — both cheap and both correct.

2. Event vs. visibility: the part everyone gets wrong

An eclipse is a single global event in time, but visibility is local. A solar eclipse is total only along a narrow path of totality (often under 200 km wide); on either side you get a partial eclipse; far enough away you see nothing.

So "is the 2026 eclipse visible from the user's location?" is really three questions:

1. Is the user inside the path of totality? → they see totality.
2. Are they inside the much wider partial zone? → they see a partial eclipse.
3. Outside both? → not visible.

The path of totality is a polygon (a long thin one). Once you have it as GeoJSON, the test is ordinary computational geometry — ray casting:

// point-in-polygon via ray casting; ring is [[lng, lat], ...]
function inside(point, ring) {
  const [x, y] = point;
  let hit = false;
  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
    const [xi, yi] = ring[i];
    const [xj, yj] = ring[j];
    const crosses = (yi > y) !== (yj > y) &&
      x < ((xj - xi) * (y - yi)) / (yj - yi) + xi;
    if (crosses) hit = !hit;
  }
  return hit;
}

For the partial zone you can either ship a second, wider polygon, or approximate: if the user is within a few thousand km of the central path, the Sun is at least partially eclipsed. For a consumer tracker the polygon test is plenty.

A subtlety worth knowing: the path of totality is computed on an idealized ellipsoid, so right at the edges (the "graze line") real visibility depends on local terrain and your exact altitude. Don't promise totality to someone sitting on the boundary — show them "edge of the path" and let them move.

3. Local timing and a countdown that survives reloads

The canon gives you the peak in UTC. Converting to the user's wall clock is a one-liner with Intl — and you should let the browser own the timezone rather than storing an offset (offsets change with DST; zones don't):

const peak = new Date("2026-08-12T18:46:13Z");
new Intl.DateTimeFormat(undefined, {
  dateStyle: "full",
  timeStyle: "long",
}).format(peak);
// → "Wednesday, 12 August 2026 at 20:46:13 CEST" for a user in Madrid

For the live countdown, the trap is setInterval(fn, 1000) as your source of truth. Intervals drift, throttle in background tabs, and pause when the device sleeps. Always recompute from the absolute target each tick:

function tick() {
  const ms = peak.getTime() - Date.now();   // recompute every frame
  render(ms);
  if (ms > 0) requestAnimationFrame(tick);
}

Date.now() is wall-clock truth; the loop just decides when to read it. Now a backgrounded tab that wakes after an hour shows the correct remaining time instead of being an hour behind.

4. Make it an installable, offline PWA

An eclipse tracker is exactly the app you want working when you're standing in a field with one bar of signal. Everything it needs — the event JSON, the path GeoJSON, the timing logic — is static, so it caches cleanly.

// service worker: cache-first for the eclipse data
const CACHE = "eclipse-v1";
const ASSETS = ["/", "/eclipses.json", "/2026-08-12-path.geojson"];

self.addEventListener("install", (e) =>
  e.waitUntil(caches.open(CACHE).then((c) => c.addAll(ASSETS)))
);

self.addEventListener("fetch", (e) =>
  e.respondWith(
    caches.match(e.request).then((hit) => hit ?? fetch(e.request))
  )
);

Add a web app manifest with display: "standalone" and the user can install it to the home screen. The countdown then runs entirely offline — the math doesn't need a network, only Date.now() and a cached target.

5. The 12 Aug 2026 path, end to end

Putting it together for one user in, say, Bilbao:

1. Load eclipses.json, find the next event with peakUTC > now → the 2026 total.
2. Geolocate the user (or let them pick a city), run the point-in-polygon test against the path GeoJSON.
3. Bilbao sits inside the path → render "Totality. ~1m 30s of darkness."
4. Convert peakUTC to local time via Intl, start the requestAnimationFrame countdown.
5. Service worker has all three files cached → it keeps counting with the phone in airplane mode.

No server round-trips at runtime, correct to the second, works in a field.

If you'd rather not build it, this is exactly what we ship at NextEclipse — a free, installable PWA that tracks every upcoming solar and lunar eclipse, with local visibility and a live countdown for your spot (including 12 Aug 2026). Built by Furiosa Studio.