Migrate from Date to Temporal
HowTo Replace Date
JavaScript Temporal was designed to replace the old Date object.
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.
Use PlainDate if you only need a date.
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;
Note
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 date = Temporal.PlainDate.from("2026-02-17");
const nextWeek = date.add({ days: 7 });
Try it Yourself »
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;
Try it Yourself »
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);
Try it Yourself »
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();
Try it Yourself »
Temporal uses ZonedDateTime for clear time zone handling.
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());
Try it Yourself »
Where to Replace Date with Temporal
Use Temporal for new applications.
Use Temporal when time zones matter.
Use Temporal when doing date arithmetic.
Keep Date if you must support older environments without Temporal.
Summary
Temporal provides safer and clearer alternatives to most Date patterns.
Temporal avoids mutation, handles time zones correctly, and simplifies date math.
For new projects, Temporal is the modern choice.
