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 = now.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;
Note: 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.
