What it is#
Nightfall is an interactive night sky for anywhere on Earth, live at https://nightfall.adrianbernhard.ch. A visitor picks a place and a moment and sees the sky as it would look from there: about 5,000 naked-eye stars, the 88 constellations, the Milky Way, the planets, the Moon in its correct phase, twilight colours and a horizon. A side panel answers "is it worth going outside tonight?": when it gets dark, which planets are up and when, the Moon's phase, and upcoming events such as eclipses visible from that place, conjunctions and meteor showers. Clicking any entry moves the sky to that moment. The sky can be dragged, zoomed, played as a time-lapse or switched to a red night-vision mode, and on phones it can follow the compass and tilt sensors. There are no accounts, no backend and no third-party requests: data and fonts ship with the app and everything is computed in the browser.
Stack#
| Area | Choice |
|---|---|
| Language | TypeScript (strict), no UI framework |
| Build | Vite 8, static output with relative paths |
| Rendering | Canvas 2D for the sky, plain DOM for the interface |
| Libraries | Astronomy Engine (ephemerides), tz-lookup (coordinates to time zone), Fontsource (self-hosted fonts) |
| Tests | Vitest, type check in GitHub Actions |
| Hosting | Static build served by nginx, deployed by Coolify on a VPS |
How it works#
Catalogues#
A Node script (scripts/build-data.mjs) compacts open datasets into JSON once, at
development time, and the output is committed. It produces 5,044 stars to magnitude 6.0
(position, magnitude, B-V colour, about 3,000 names), 88 constellation figures, the 110
Messier objects, 7,280 cities with IANA time zones, and the Milky Way. The Milky Way arrives
as nested brightness contours; the script rasterises them onto a 1° RA/Dec grid, so the
app only needs a lookup table.
From place and time to positions#
Catalogue positions become J2000 unit vectors once, at startup. For each frame, Astronomy
Engine supplies one 3x3 rotation from J2000 into the observer's horizontal frame for that
instant and location. It includes precession, nutation and Earth's rotation, so a single
matrix multiply per star gives its direction in the observer's sky; standard refraction is
added near the horizon. A unit test checks this path against Astronomy Engine's own
Horizon(). The Sun, Moon and planets are computed per frame as topocentric positions,
with magnitude, phase and distance.
The "Tonight" report samples Sun, Moon and planet altitudes every 10 minutes from local noon to the next noon, then uses Astronomy Engine's searches for exact sunset, twilight and rise/set times. Upcoming events (eclipses, oppositions, elongations, conjunctions, meteor showers, seasons) are searched over the coming months, and eclipses are kept only if they can be seen from the chosen place.
Time zones#
"Tonight" means the local night of the chosen place, not of the visitor's browser.
Nightfall ships no time-zone database: it uses Intl.DateTimeFormat with the place's IANA
zone to convert between UTC and wall-clock time, DST included. A night runs from local
noon to local noon, so 02:00 belongs to the previous evening. On a first visit the place
is guessed from the browser's time zone with a small table from IANA zone to city, so there
is no permission prompt. That table loads at startup only when no place is saved yet.
Rendering and performance#
The view uses a stereographic projection, which keeps constellation shapes undistorted and maps the horizon to a circle that is easy to fill as ground. The sky background is a per-pixel model of zenith and horizon colours, twilight glow, Sun and Moon glare, light pollution and the Milky Way. The number of stars drawn follows a limiting magnitude derived from twilight, the chosen sky quality (city to dark site), moonlight and zoom.
Keeping it fast:
- The sky background is computed at one fifth of the screen resolution and scaled up smoothly; its inverse projection per pixel is algebraic, with no trigonometry.
- A frame is drawn only when something changed, never while the tab is hidden, and the device pixel ratio is capped at 2.
- The night report is recomputed only when the place or the night changes, and upcoming events at most once per simulated day, after the frame.
- The city list loads only for a place search, GPS or typed coordinates, and the coordinates-to-time-zone lookup only for GPS and coordinates. A first visit transfers about 295 KB compressed, mostly the star catalogue, the app code and the fonts.
flowchart TB
subgraph build["Build time"]
D["Open datasets"] --> S["build-data.mjs"] --> J["src/data/*.json"]
end
subgraph browser["Browser"]
J --> C["J2000 unit vectors"]
P["Place + time"] --> AE["Astronomy Engine"]
AE --> R["Horizon frame,<br/>Sun, Moon, planets"]
C --> R --> V["Stereographic camera"] --> K["Canvas frame"]
AE --> T["Tonight report, events"] --> U["Side panel"]
end
State lives in a small store; settings and the last place persist in localStorage.
Share links put place, time and selected object in the URL hash, so the static host needs
no rewrite rules.
Data sources and licences#
| Data or asset | Source | Licence |
|---|---|---|
| Stars, names, constellations, Messier objects, Milky Way | d3-celestial by Olaf Frohn (compiled from XHIP, SEDS and J. R. Vieira's Milky Way outlines) | BSD-3-Clause |
| Ephemerides, eclipses, coordinate frames | Astronomy Engine by Don Cross | MIT |
| Cities and time zones | city-timezones | MIT |
| Coordinates to time zone | @photostructure/tz-lookup | CC0 |
| Fonts (Fraunces, Inter) | Fontsource | SIL Open Font License |
The short notes on famous stars, constellations and deep-sky objects were written for Nightfall.
Testing and quality#
- Unit tests (Vitest, 25 tests): time zones across DST and the "night starts at noon"
rule; the horizon rotation against
Horizon(); night reports for a normal night, the southern hemisphere, midnight sun and polar night; event ordering; projection round-trips; share links, including bad input; search and object details; the phone sensor maths; eclipse geometry; that every note matches a catalogue object; and the link-preview tags and image. - Type checking: strict TypeScript with unused locals and parameters as errors.
- CI: GitHub Actions runs the type check and the tests on every push to
mainand on pull requests. - Manual testing: the interface was exercised in Chrome on the production build at desktop, tablet and phone widths, including eclipse dates and polar locations.
Deployment#
The build is a static site with relative paths, so it can be hosted anywhere. Live, a
two-stage Dockerfile builds it on Node 22 with the heap capped at 384 MB and serves it
with nginx:alpine. The type check runs in CI rather than in the image, to keep the
build's memory peak low on a small VPS. Coolify deploys every push to main. nginx caches
the hashed assets for a year, serves index.html with no-cache so a deploy shows up
immediately, and compresses text assets.
Link previews use a 1200x630 card with absolute og:image and og:url URLs, since social
networks don't resolve relative ones. It comes from the same card generator as
adrianbernhard.ch, and a test checks the tags and image size.
Design decisions and trade-offs#
- No framework, no backend. A canvas, a few DOM components and a tiny store keep the app small, static and free to host, at the cost of writing dialogs and panels by hand.
- An ephemeris library, not hand-written astronomy. Astronomy Engine is accurate and tested, so the app builds on its frames and searches. It also inherits its limits: for example, it only reports solar eclipses with the Sun above the horizon.
- Canvas 2D with a low-resolution sky pass, not WebGL. It runs everywhere and is easy to debug; WebGL would allow a full-resolution sky and deeper catalogues, but adds complexity and fallbacks.
- Committed, pre-processed catalogues. No runtime requests and no API to depend on, but the sky is fixed to naked-eye stars and the Messier list.
Known limits and next steps#
- Not modelled: weather, real terrain (the horizon hills are decorative), satellites, comets and asteroids, and deep-sky objects beyond the Messier list.
- The phone sensor mode was verified with synthetic orientation events only; magnetic declination is not corrected, and pinch zoom was not tested on real multi-touch hardware.
- Meteor-shower peaks use fixed calendar dates and can be a day off. Conjunction distances are geocentric, so they can differ by about 1° for the Moon.
- English only; times and dates follow the visitor's locale.
- Possible next steps: a real horizon from elevation data, the ISS, and a deeper star catalogue loaded on demand when zooming in.