// the find
mourner/suncalc
A tiny JavaScript library for calculating sun/moon positions and phases.
SunCalc computes sun and moon positions, rise/set times, lunar phases, and twilight boundaries for any lat/lng and date. It's a single-file, zero-dependency library built on Jean Meeus' Astronomical Algorithms, so the math is sound rather than interpolated from lookup tables. The target audience is anyone building outdoor, photography, astronomy, or farming apps that need celestial timing without pulling in a full ephemeris.
The accuracy story is unusually honest — ~0.08° position error and ~15s rise/set error, validated against JPL Horizons, not just eyeballed. The v2.0 rewrite fixed a long-standing azimuth convention inconsistency (now clockwise from north, matching every compass ever made) and switched altitude to degrees, which is what humans actually use. The `addTime` escape hatch for custom solar angle events is the right API decision — blue hour, blue-hour photography brackets, civil vs nautical split — all handled without forking. Zero dependencies and a sub-5KB footprint mean it drops into any environment without negotiation.
getMoonTimes scans a fixed UTC calendar day, which silently gives wrong results if your user's local midnight doesn't align with UTC midnight — the README documents this but it's a foot-gun in practice and the fix (passing local midnight) requires the caller to do timezone math that many won't bother with. There's no TypeScript-first implementation; `index.d.ts` is a hand-maintained declaration file bolted on the side, so type drift is a real risk as the JS evolves. The library has no concept of atmospheric refraction parameters — the refraction correction is baked in with standard assumptions, so it's wrong at extreme altitudes or unusual pressure/temperature conditions where refraction deviates significantly. addTime mutates global state, which is a problem in any multi-tenant or SSR context where one caller's custom times bleed into another request's results.