HowTo Replace Date
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.
Replace new Date()
With Date, you create a date like this:
Date Example
const d = new Date();With Temporal, choose the type you need.
Temporal Example
const instant = Temporal.Now.instant();Use PlainDate if you only need a date.
Temporal Date Only
const today = Temporal.Now.plainDateISO();Replace Date.now()
Date provides timestamps in milliseconds.
Date Example
const timestamp = Date.now();With Temporal, use Instant .
Temporal Example
const now = Temporal.Now.instant();
const timestamp = instant.epochMilliseconds);Replace getFullYear(), getMonth(), getDate()
Date uses getter methods.
Date Example
const d = new Date();
let year = d.getFullYear();
let month = d.getMonth();
let day = d.getDate();Temporal exposes properties directly.
Temporal Example
const date = Temporal.Now.plainDateISO();
let year = date.year;
let month = date.month;
let day = date.day;Months start at 1, not 0.
Replace setDate() and Other Mutating Methods
Date changes the original object.
Date Example
const d = new Date("2026-05-17");
d.setDate(d.getDate() + 7);Temporal does not mutate values.
Temporal Example
const date = Temporal.PlainDate.from("2026-02-17");
const nextWeek = date.add({ days: 7 });Replace Date Arithmetic
Date often requires manual millisecond calculations.
Date Example
const start = new Date("2026-05-01");
const end = new Date("2026-05-17");
const duration = end - start;Temporal provides built-in duration calculations.
Temporal Example
const start = Temporal.PlainDate.from("2026-05-01");
const end = Temporal.PlainDate.from("2026-05-17");
const duration = start.until(end);Replace Time Zone Handling
Date mixes local time and UTC.
This makes time zone handling confusing.
Date Example
let d = new Date();
let time1 = d.toString();
let time2 = d.toUTCString();Temporal uses ZonedDateTime for clear time zone handling.
Temporal Example
const zoned = Temporal.Now.zonedDateTimeISO();Convert Date to Temporal
You can convert an existing Date to a Temporal Instant.
Example
const d = new Date();
const instant = Temporal.Instant.fromEpochMilliseconds(d.getTime());Where to Replace Date with Temporal
- 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.