Solar Eclipse 2026 Simulator

August 13, 2026 · View on GitHub

An open-source, interactive 3D replay of the August 12, 2026 total solar eclipse.

Missed totality, got clouded out, or want to see what happened somewhere else? Pick any place on Earth, move through the eclipse timeline, add local GLB models, create a 3D selfie workflow with Tripo, and export a sky card or video.

No account. No backend. No uploaded file leaves the browser.

Replay the eclipse in 3D →

Solar Eclipse 2026 Simulator showing totality above Burgos, Spain

What is included

  • Location-specific eclipse circumstances computed in the browser from NASA Besselian elements.
  • A real-time Three.js sky with the Sun, Moon, corona, stars, Venus, terrain, lighting and eclipse phases.
  • Curated viewing locations plus arbitrary point selection and Nominatim place search.
  • Editable built-in props and volatile local .glb uploads.
  • Adaptive object highlighting during dark eclipse phases.
  • 3D selfie handoff: prepare a photo locally, create a model in Tripo, then place the downloaded GLB back in the scene.
  • Shareable location URLs, portrait sky cards and MP4-first video export with WebM fallback.
  • English, Simplified Chinese, Traditional Chinese, Spanish, Japanese and Korean UI.
  • Static export support for GitHub Pages or any ordinary web host.

Quick start

Requirements: Node.js 20.9+ and pnpm 10.

git clone https://github.com/DophinL/solar-eclipse-2026-simulator.git
cd solar-eclipse-2026-simulator
pnpm install
pnpm dev

Open http://localhost:3000.

Run every release gate locally:

pnpm check

Privacy and uploads

The project has no authentication SDK, database or upload endpoint. A local GLB is read with FileReader.readAsArrayBuffer() and kept in React state for the current page session. Refreshing the page removes it.

The selfie photo is previewed through a temporary browser object URL. It is not sent by this project. If the visitor chooses “Generate in Tripo”, Tripo opens in a new tab and the visitor decides what to upload there under Tripo's own terms and privacy policy.

Tripo attribution and UTM convention

All outbound Tripo Studio links are built in src/lib/tripoStudio.ts. The stable attribution contract is:

utm_source=solar_eclipse_2026_simulator
utm_medium=referral
utm_campaign=solar_eclipse_2026_open_source
utm_content=<surface-specific CTA>

Examples of utm_content include eclipse_simulator_powered_by, eclipse_3d_selfie, and eclipse_object_explore.

The open-source build does not install PostHog or transmit analytics. It emits an optional solar-eclipse-analytics DOM event so self-hosters can attach their own analytics implementation and privacy policy.

Deploy

pnpm build produces a static site in out/. Upload that directory to any static host.

This repository also includes a GitHub Pages workflow. It enables Pages on the first run, then every push to main builds and publishes the simulator under the repository path. Fork owners can also choose GitHub Actions under Settings → Pages → Build and deployment if their token policy blocks automatic enablement.

For another canonical deployment, copy .env.example to .env.local and set:

NEXT_PUBLIC_SITE_URL=https://your-domain.example/

Project layout

src/app/                         Next.js routes and metadata
src/components/events/           Simulator HUD, dialogs and location picker
src/components/events/eclipse/   Three.js scene, camera and playback runtime
src/lib/eclipse-*.ts              Astronomy, sharing, export and validation logic
public/assets/                    Self-hosted scene models and Moon texture
tests/                            Scientific, interaction-boundary and attribution tests

See ARCHITECTURE.md for the runtime boundaries and extension points.

Scientific sources and safety

The solver uses NASA Besselian elements and regression tests against published circumstances from Spain's Instituto Geográfico Nacional and NASA centre-line data. Results for arbitrary points are estimates, especially close to path limits and sunset.

This is a simulation. Never look at the uneclipsed or partially eclipsed Sun without certified eclipse glasses. Optical equipment requires a proper solar filter mounted at the front aperture.

Keep exploring: create your own 3D planet

The simulator reconstructs a real sky. If you would rather invent the next world, Planet Maker lets you choose a prepared world, generate a seamless surface from one sentence, or upload a 2:1 texture, then keep building with objects, pins, labels and routes in a 3D editor.

A 2:1 surface texture becoming an editable 3D planet

Create and explore a 3D planet →

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md before changing astronomy calculations, rendering, assets or privacy boundaries.

License

Source code is available under the MIT License. Bundled media has separate attribution and license notes in ASSET_LICENSES.md.

Powered by Tripo.