JavaScript Temporal vs Date

Learn the differences between JavaScript Date and Temporal

• Date months are 0-based, Temporal months are 1-based
• Date arithmetic is manual, Temporal is built-in
• Date mutates values, Temporal does not
• Date mixes UTC and time zones, Temporal separates them
• Date can fail in DST handling, Temporal can not

Learn why Temporal is the modern alternative to Date.

Share

JavaScript Date Problems

The JavaScript Date object is old and has several design problems.

These are the most common mistakes developers make when using Date objects:

• Using the wrong month number because months start at 0.
• Accidentally changing a date object by calling a mutating method.
• Parsing unclear strings that behave differently across environments.
• Mixing local time and UTC values in the same program.
• Doing math across DST changes and getting unexpected hours.

Date Months are 0-Based

In the JavaScript Date object, January is month 0 and December is month 11.

Date Example

// May 17, 2026:

let date = new Date(2026, 4, 17)

Temporal Months are 1-Based

In the JavaScript Temporal object, January is month 1 and December is month 12.

This is much more user-friendly.

Temporal Example

// May 17, 2026:

const date = new Temporal.PlainDate(2026, 5, 17)

Date Objects are Mutable

JavaScript Date objects can change.

Date objects are mutable.

Date Example

// Create a Date

const date = new Date("2026-05-17");

// Add 7 days to date

date.setDate(date.getDate() + 7);

// Here the original date is lost

Date Example

// Create a Date

const date1 = new Date("2026-05-17");

// Create a copy

const date2 = date1;

// Add 7 days to date1

date1.setDate(date1.getDate() + 7);

// Here date2 has changed

Temporal Objects are Immutable

JavaScript Temporal objects cannot change.

Temporal objects are immutable.

Temporal Example

// Create a Date

const date1 = Temporal.PlainDate.from("2026-05-17");

// Add 7 days

const date2 = date1.add({ days: 7 });

// Here original date1 is kept

Date Parsing is Inconsistent

JavaScript has been a minefield of different formats, browser quirks and locale surprises.

Date strings can be parsed differently across browsers and environments, and different formats may be interpreted as local time or UTC.

A date string like 2026-05-07 is interpreted as UTC time in JavaScript.

A date-time string like 2026-05-07T14:40:00 is interpreted as local time.

Date Example

const d1 = new Date("2026-05-17");

const d2 = new Date("2026-05-17T00:00:00");

const d3 = new Date("05/17/2026");

const d4 = new Date("May 17 2026");

const d5 = new Date("17 May 2026");

const d6 = new Date(2026, 4, 17);

Temporal PlainDate

Temporal avoids the problems above by defining strict parsing rules for ISO strings.

Temporal.PlainDate is not a timestamp.

It is just 2026-05-17 with no time and no time zone.

Temporal Example

// Create a PlainDate object

const date = Temporal.PlainDate.from("2026-05-17");

Date and Time Zone

new Date(2026, 4, 1) creates a timestamp of your local time at midnight.

This means a day can "shift" when you format it to UTC.

Date Example

// Create a Date object

const date = new Date(2026, 4, 1);

// Might be another day in some time zones:

date.toISOString();

Date Mixes Local Time and UTC

A Date object always stores a timestamp, but it can display values as local time or UTC.

This mix can easily cause confusion when converting and comparing dates.

The same moment can look different depending on how it is displayed.

Date Example

const date = new Date();

let time1 = date.toString();

let time2 = date.toUTCString();

Temporal Separates Time and UTC

Temporal uses clear types for time zones.

Temporal.ZonedDateTime always includes a time zone.

Temporal Example

const instant = Temporal.Now.instant();

const local = Temporal.Now.zonedDateTimeISO();

DST Can Break Date Math

Daylight saving time (DST) can cause a day to be 23 or 25 hours long.

This can break calculations that assume every day is exactly 24 hours.

Example

const start = new Date("2026-03-29T00:00:00");

const end = new Date(start.getTime() + 24 * 60 * 60 * 1000);

The result can be off by one hour in time zones with DST changes.

Date Math

Date math often requires manual calculations.

Date Example

const start = new Date("2026-05-01");

const end = new Date("2026-05-17");

const diff = end - start;

Temporal has built-in date arithmetic.

Temporal Example

const start = Temporal.PlainDate.from("2026-05-01");

const end = Temporal.PlainDate.from("2026-05-17");

const diff = start.until(end);

Date Mixes Everything

Date mixes everything in one object.

Date (Problem)

const date = new Date(); // date + time + zone

Temporal Uses Clear Types

Temporal objects separate different use cases into different objects.

This makes code easier to read and less error-prone.

Differences Between Date and Temporal

When to Use Temporal?

• You need correct time zone handling.
• You work with international users.
• You want safe date arithmetic.
• You want clear and modern code.