The JavaScript Temporal API

Date has three problems that have shaped an entire ecosystem of workaround libraries (Moment.js, date-fns, Day.js): it's mutable, it conflates a moment in time with a calendar date, and it has essentially no built-in timezone support beyond the local system zone and UTC. Temporal, a newer built-in API, is designed specifically to fix all three without needing a third-party library.

Immutability

Every Date method that looks like it returns a new date — setDate(), setMonth() — actually mutates the original object in place, a classic source of subtle bugs when a date object is shared or passed around. Every Temporal type is immutable: operations like .add() or .with() always return a new object, leaving the original untouched.

Separate types for separate concepts

Date forces every value — a birthday, a meeting time, a pure calendar date — into the same single type, tied to a specific instant and implicitly a timezone. Temporal splits this into distinct types that match what you're actually representing: Temporal.PlainDate for a date with no time or zone (a birthday), Temporal.PlainTime for a time with no date, Temporal.ZonedDateTime for a specific instant tied to a real IANA timezone, and Temporal.Instant for a raw point on the UTC timeline — closest to what a Unix timestamp represents.

Real timezone support, without a library

Temporal.ZonedDateTime works directly with IANA timezone identifiers (the same ones used throughout this site, like America/New_York) and correctly handles daylight saving transitions, including the genuinely tricky edge cases — like what happens to a time that falls in the repeated hour during a fall-back transition — that most hand-rolled Date-based code gets wrong.

A quick example

const meeting = Temporal.ZonedDateTime.from({
  timeZone: "America/New_York",
  year: 2027, month: 3, day: 14, hour: 9
});
const tokyoTime = meeting.withTimeZone("Asia/Tokyo");
console.log(tokyoTime.toString());

Should you switch today?

Check current browser and runtime support before relying on it in production without a polyfill — it's a newer addition to the language, and older environments won't have it natively. For new projects targeting current environments, it's worth using directly instead of reaching for a legacy date library out of habit.