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.
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.
