Migrate from Date to Temporal
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
With Temporal, choose the type you need.
Use PlainDate if you only need a date.
Replace Date.now()
Date provides timestamps in milliseconds.
Date Example
With Temporal, use Instant.
Temporal Example
const timestamp = now.epochMilliseconds;
Replace getFullYear(), getMonth(), getDate()
Date uses getter methods.
Date Example
let year = d.getFullYear();
let month = d.getMonth();
let day = d.getDate();
Temporal exposes properties directly.
Temporal Example
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.
Temporal does not mutate values.
Temporal Example
const nextWeek = date.add({ days: 7 });
Replace Date Arithmetic
Date often requires manual millisecond calculations.
Date Example
const end = new Date("2026-05-17");
const duration = end - start;
Temporal provides built-in duration calculations.
Temporal Example
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 time1 = d.toString();
let time2 = d.toUTCString();
Temporal uses ZonedDateTime for clear time zone handling.
Convert Date to Temporal
You can convert an existing Date to a Temporal Instant.
Example
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.