Loading lesson path
JavaScript Temporal was designed to replace the old Date object. For new JavaScript projects, Temporal is the modern choice. Temporal provides safer and clearer alternatives to Date patterns. Temporal handles time zones correctly. Temporal avoids mutation and simplifies date math. This chapter shows how to migrate from Date code to modern Temporal code.
With Date, you create a date like this:
const d = new Date();With Temporal, choose the type you need.
const instant = Temporal.Now.instant();PlainDate if you only need a date.
Temporal Date Only const today = Temporal.Now.plainDateISO();
Replace Date.now()Date provides timestamps in milliseconds.
const timestamp = Date.now();With Temporal, use Instant.
const now = Temporal.Now.instant();
const timestamp = instant.epochMilliseconds);
Replace getFullYear(), getMonth(), getDate()Date uses getter methods.
const d = new Date();
let year = d.getFullYear();
let month = d.getMonth();
let day = d.getDate();Temporal exposes properties directly.
const date = Temporal.Now.plainDateISO();
let year = date.year;
let month = date.month;
let day = date.day;Months start at 1, not 0.
Date changes the original object.
const d = new Date("2026-05-17");
d.setDate(d.getDate() + 7);Temporal does not mutate values.
const date = Temporal.PlainDate.from("2026-02-17");
const nextWeek = date.add({ days: 7 });Date often requires manual millisecond calculations.
const start = new Date("2026-05-01");
const end = new Date("2026-05-17");
const duration = end - start;Formula
Temporal provides built - in duration calculations.const start = Temporal.PlainDate.from("2026-05-01");
const end = Temporal.PlainDate.from("2026-05-17");
const duration = start.until(end);Date mixes local time and UTC. This makes time zone handling confusing.
let d = new Date();
let time1 = d.toString();
let time2 = d.toUTCString();ZonedDateTime for clear time zone handling.
const zoned = Temporal.Now.zonedDateTimeISO();You can convert an existing Date to a Temporal Instant.
const d = new Date();
const instant = Temporal.Instant.fromEpochMilliseconds(d.getTime());Use Temporal for new applications. Use Temporal when time zones matter. Use Temporal when doing date arithmetic. Use Date if you must support older environments.