Loading lesson path
Learn the differences between JavaScript Date and Temporal
Formula
Date months are 0 - based, Temporal months are 1 - based
Date arithmetic is manual, Temporal is built - inDate 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.
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 object has been used since 1995. Temporal is the modern replacement designed to fix many of Date's problems.
Formula
Date Months are 0 - BasedIn the JavaScript Date object, January is month 0 and December is month 11.
// May 17, 2026:
let date = new Date(2026, 4, 17)The Date object is confusing because most people expect January to be month 1.
Formula
Temporal Months are 1 - BasedIn the JavaScript Temporal object, January is month 1 and December is month 12. This is much more user friendly.
// May 17, 2026:
let new Temporal.PlainDate(2026, 5, 17)JavaScript Date objects can change. Date objects are mutable.
Date methods can change the original date object:
// Create a Date let date = new Date("2026-05-17");
// Add 7 days to date date.setDate(date.getDate() + 7);// Here the original date is lost
Date methods can change other date objects:
// Create a Date let date1 = new Date("2026-05-17");
// Create a copy let date2 = date1;
// Add 7 days to date1 date1.setDate(date1.getDate() + 7);// Here date2 has changed In the example above, the variables date1 and date2 point to the same object. So date2 changes when date1 changes. This can create unexpected results when date values are copied or reused.
JavaScript Temporal objects cannot change. Temporal objects are immutable.
(or value).
// Create a Date let date1 = Temporal.PlainDate.from("2026-05-17");Formula
// Add 7 days let date2 = date1.add({ days: 7 });// Here original date1 is kept
Formula
2026 - 05 - 07 parses as anUTC instant in JavaScript. 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.
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 avoids the problems above by defining strict parsing rules for ISO strings. Temporal.PlainDate is not a timestamp.
Formula
2026 - 05 - 17 with no time and no time zone.const date = Temporal.PlainDate.from('2026-05-17');It is safer to avoid unclear formats and use explicit formats when possible. 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.
// Create a Date object const date = new Date(2026, 4, 1);// Might be another day in some time zones:
date.toISOString();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.
let date = new Date();
let time1 = date.toString();
let time2 = date.toUTCString();Temporal uses clear types for time zones. Temporal.ZonedDateTime always includes a time zone.
const instant = Temporal.Now.instant();
const local = Temporal.Now.zonedDateTimeISO();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.