Handle time correctly for users everywhere: instants vs calendar dates vs wall times, the classic bugs, formatting with Intl, daylight saving gaps and overlaps, converting wall time in any zone to an instant, relative times, Temporal, storage and API rules, and SSR hydration.
Most date bugs come from treating different kinds of time as if they were the same thing. There are three, and every value in your app is one of them:
| Kind | Example | What it means | Store it as |
|---|---|---|---|
| Instant | "Payment received", "Message sent" | One exact moment, the same everywhere on Earth | UTC: 2026-11-05T14:30:00Z (or milliseconds since 1970) |
| Calendar date | Birthday, due date, holiday | A day on the calendar, with no time and no zone | "2026-03-10" (a string) |
| Wall time in a zone | "Standup at 9:00 in New York", store opening hours | What the clock on the wall shows, in a specific place | Date and time plus an IANA zone: 2026-03-09 09:00 + America/New_York |
Why the difference matters:
Time zones are named places, not offsets. America/New_York (an IANA time zone name) knows its whole history: when daylight saving time starts and ends, and past rule changes. An offset like -05:00 is only a snapshot: it's New York in winter, but also Bogotá all year, and wrong for New York in July. Store zone names, never offsets.
JavaScript's Date is always an instant. Internally it's milliseconds since 1970 UTC. It has no time zone of its own; methods like getHours() and toString() quietly use the device's zone, which is where many bugs come from.