Every JavaScript developer has, at some point, fought with the Date object and lost. It is mutable, it counts months from zero, it silently accepts nonsense, and it has no real concept of time zones. For years the answer was “just use a library.” Now there’s a better one: the JavaScript Temporal API, a new built-in designed from scratch to fix dates and times properly.
Why Date had to be replaced, not patched
The problems with Date are baked into its design. Months are zero-indexed, so December is 11. It’s mutable, so passing a date around risks something changing it underneath you. It conflates the idea of “an instant in time” with “a calendar date” with “a wall-clock time,” even though those are genuinely different concepts. You can’t fix that with a few new methods — you need a new model. That’s what Temporal provides.
Separate types for separate concepts
The core insight of Temporal is that “a date” isn’t one thing. It gives you distinct, immutable types for each real-world concept:
Temporal.PlainDate— a calendar date with no time or zone (a birthday).Temporal.PlainTime— a wall-clock time with no date (an alarm).Temporal.PlainDateTime— both, but still no time zone.Temporal.ZonedDateTime— a precise moment in a specific time zone.Temporal.Instant— an exact point on the global timeline.
Choosing the right type makes your intent explicit and eliminates a whole class of bugs where a “date” accidentally carried a time zone it shouldn’t have.
It reads like you’d hope
// A date, done right
const today = Temporal.Now.plainDateISO();
const nextWeek = today.add({ days: 7 });
console.log(nextWeek.toString()); // 2026-07-14
console.log(nextWeek.dayOfWeek); // no zero-indexing surprises
// Immutable: 'today' is unchanged
Notice three things: month and day math just works, the objects are immutable so today is never mutated, and the API is explicit about what kind of value you’re holding. Arithmetic, comparisons, and formatting all follow the same predictable pattern.
Time zones that finally make sense
Where Date basically gave up on time zones, Temporal treats them as first-class. A ZonedDateTime knows its zone, handles daylight-saving transitions correctly, and converts between zones without the guesswork and off-by-one-hour bugs that have haunted scheduling apps forever.
Using it today
Temporal is rolling out across browsers and runtimes, and where native support isn’t available yet, an official polyfill lets you adopt the exact same API now. The practical move is to reach for Temporal on new date-handling code and let your old Date usage retire naturally. You do not need a big-bang migration.
Durations and the arithmetic Date never had
Beyond the date types, Temporal adds Temporal.Duration — a first-class “amount of time” — and with it, the arithmetic that used to require a library or fragile millisecond math:
const start = Temporal.PlainDate.from('2026-01-15');
const end = Temporal.PlainDate.from('2026-07-08');
const gap = start.until(end); // a Duration
console.log(gap.days); // total difference in days
// Or in the units you actually want:
console.log(start.until(end, { largestUnit: 'months' }).toString());
// e.g. P5M23D — 5 months, 23 daysNotice what’s absent: no dividing by 86,400,000, no off-by-one from daylight saving shifts, no wondering whether “a month” is 30 or 31 days — you state the units and the calendar does the counting. Comparisons got the same upgrade: Temporal.PlainDate.compare(a, b) sorts dates correctly out of the box, and .equals() means value equality, not the reference-identity trap where two identical Date objects are “not equal.”
A real bug Temporal makes impossible
Consider the scheduling classic: a meeting at 9:00 AM New York time, displayed to a user in Berlin. With Date, someone inevitably constructs new Date('2026-11-01T09:00:00') — which silently means 9 AM in whatever timezone the server or browser happens to run in. It works in testing (everyone’s in one timezone), then breaks in production, and breaks differently the week clocks change, because November 1st straddles a daylight-saving transition in the US but not in Europe.
Temporal forces the ambiguity into the open: a PlainDateTime can’t be misread as an instant because it isn’t one — converting it to a real moment requires naming the zone: plainDateTime.toZonedDateTime('America/New_York'). From there, .withTimeZone('Europe/Berlin') converts correctly, DST included, because the timezone database does the work instead of your assumptions. The bug class doesn’t get fixed — it stops compiling into existence.
Migrating a codebase without a rewrite
The boundary between old and new code is well-paved. Temporal.Instant.fromEpochMilliseconds(date.getTime()) converts any legacy Date into Temporal’s world; new Date(instant.epochMilliseconds) goes back for libraries that still demand a Date. The practical migration path: adopt Temporal at the edges where bugs live — anything involving timezones, recurring schedules, or date arithmetic — and let display-only code keep using what works. Two supporting notes: Intl.DateTimeFormat accepts Temporal objects for localized formatting, and Temporal’s toString() output is clean ISO 8601, so serialized dates in your APIs and databases don’t change shape at all.
Frequently asked questions
Can I use Temporal in production right now? Yes, via the official polyfill (@js-temporal/polyfill), which implements the finalized spec and simply defers to native implementations as browsers ship them. The API is stable — code written today against the polyfill is code written for the standard.
Does Temporal replace libraries like date-fns, Day.js, or Moment? Largely, over time. Those libraries exist mostly to compensate for Date‘s gaps — safe arithmetic, parsing, timezone handling — which Temporal covers natively. What remains for libraries is convenience formatting (“3 hours ago”) and legacy support. Moment’s own maintainers recommend new projects look toward Temporal.
Which type should I reach for most often? A good default map: user-facing calendar concepts (birthdays, due dates) → PlainDate; logging and event timestamps → Instant; anything scheduled in a real place (meetings, deadlines with a timezone) → ZonedDateTime. If you’re unsure, ask “does a timezone change alter what I mean?” — no means Plain, yes means Zoned.
The takeaway
The JavaScript Temporal API is the fix a generation of developers has been asking for: immutable, explicit, time-zone-aware, and free of Date‘s decades-old traps. If dates in your codebase have ever caused a bug you couldn’t quite explain, this is the tool that makes those bugs stop happening.
