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

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;

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.