A free Temporal cheatsheet for modern JavaScript dates

JavaScript's Date has been broken since 1995. Months start at zero, mutating a date silently changes the original, timezones aren't really supported, and parsing an ISO string can behave differently across browsers. Every JavaScript developer has been bitten by it at least once.

Temporal is the fix. It's a new built-in API that replaces Date with something immutable, timezone-aware, and predictable. It just shipped in Chrome 144 and Firefox 139, is coming soon to Safari, and there's a polyfill available for older browsers, so it's finally usable in production.

I put together a free cheatsheet with side-by-side Date vs Temporal comparisons for the operations you do every day: learnjavascript.online/temporal.html.

Why Temporal matters

• 1-indexed months. January is finally 1, not 0.
• Immutable. Every operation returns a new object, so nothing else in your code silently changes.
• Timezone-aware. ZonedDateTime treats timezones as first-class, including DST transitions.
• Unambiguous parsing. ISO strings mean the same thing everywhere.
• Durations as first-class values. "3 days 2 hours" is a real type, not a tangle of milliseconds.

A quick taste

Adding 7 days to today with Date:

const d = new Date();
d.setDate(d.getDate() + 7);
// mutated in place, timezone behaviour unclear

With Temporal:

const next = Temporal.Now.plainDateISO().add({ days: 7 });
// brand new object, no mutation, no ambiguity

The types worth knowing first

• Temporal.PlainDate — a calendar date with no time or timezone. Use it for birthdays, deadlines, anything that's "just a date."
• Temporal.ZonedDateTime — date, time, and timezone together. Use it when a real moment in a real place matters.
• Temporal.Duration — a span of time like "3 hours 15 minutes." Add or subtract it from any Temporal object.

There are a few more (PlainTime, PlainDateTime, Instant, and the Temporal.Now namespace), and the cheatsheet walks through each one with a real example.

Browser support today

• Chrome 144+
• Firefox 139+
• Safari implementation in progress, polyfill available

Grab the cheatsheet

If you're moving off Date or learning Temporal for the first time, I made this to be the side-by-side reference I wish I had: learnjavascript.online/temporal.html. Enjoy!