Migrating From Date to Temporal: A Practical JavaScript Guide

JavaScript’s Date object has been wrong in the same handful of ways for thirty years: it’s mutable, it conflates calendar dates with specific instants, months are zero-indexed for no defensible reason, and time zone handling barely exists. Temporal fixes all of it, and as of this year it’s no longer a proposal you have to explain to your team. It reached TC39 Stage 4 in March 2026 and now ships unflagged in Chrome 144, Firefox 139, Edge 144, and Node.js 26. If your codebase has a utils/date-helpers.js file full of defensive workarounds, this is the year to start replacing it.

Why this isn’t just a new Date constructor

The core design decision in Temporal is splitting “a date” into several distinct, immutable types, based on what information you actually have:

Type	Represents	Example use case
Temporal.PlainDate	A calendar date, no time, no zone	A birthday, a deadline, a holiday
Temporal.PlainTime	A wall-clock time, no date, no zone	”Store opens at 9:00 AM”
Temporal.PlainDateTime	A date and time, no zone	A form field for “meeting time” before you know the zone
Temporal.ZonedDateTime	A specific instant, tied to a time zone and calendar	An actual scheduled meeting, a log timestamp shown to a user
Temporal.Instant	A specific point on the UTC timeline, no calendar	Raw timestamps for storage or comparison
Temporal.Duration	An elapsed amount of time	”3 days and 2 hours”

Date tried to be all six of these at once, which is why so much Date-related code has comments like // careful, this breaks near DST. Temporal makes you be explicit about which one you have, and the type system (or at minimum, the object you’re holding) won’t let you accidentally do zone-aware arithmetic on a value that has no zone.

Common Date patterns, migrated

Getting “today” as a date, not a timestamp

// Date: you get a full instant, then have to extract just the date parts
const today = new Date();
const dateOnly = `${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, "0")}-${String(today.getDate()).padStart(2, "0")}`;

// Temporal: PlainDate is already just a date
const today = Temporal.Now.plainDateISO();
today.toString(); // "2026-07-16", no formatting gymnastics

Adding time, correctly, across DST

// Date: this can land on the wrong wall-clock hour across a DST transition
const meeting = new Date("2026-03-08T09:00:00");
meeting.setDate(meeting.getDate() + 1); // silently drifts an hour in some zones

// Temporal: ZonedDateTime.add() handles the calendar and the zone correctly
const meeting = Temporal.ZonedDateTime.from("2026-03-08T09:00:00-05:00[America/New_York]");
const nextDay = meeting.add({ days: 1 });
nextDay.toString(); // still 09:00 local time, DST-adjusted correctly

Comparing dates without timestamp footguns

// Date: comparing requires converting to timestamps, and time-of-day can throw off "same day" checks
const a = new Date("2026-07-16T23:00:00");
const b = new Date("2026-07-17T01:00:00");
a.getTime() < b.getTime(); // true, but are these "the same day"? Depends on zone, easy to get wrong.

// Temporal: PlainDate strips time entirely, so the comparison means what it says
const a = Temporal.PlainDate.from("2026-07-16");
const b = Temporal.PlainDate.from("2026-07-17");
Temporal.PlainDate.compare(a, b); // -1, unambiguous

Formatting for display

Temporal integrates directly with Intl, so you don’t need a separate formatting library for locale-aware output:

const date = Temporal.PlainDate.from("2026-07-16");
new Intl.DateTimeFormat("en-US", { dateStyle: "long" }).format(date);
// "July 16, 2026"

new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
// "16. Juli 2026"

Calculating a duration between two events

// Date: manual millisecond math, then manual conversion back to human units
const start = new Date("2026-07-01T09:00:00Z");
const end = new Date("2026-07-16T14:30:00Z");
const diffMs = end - start;
const days = Math.floor(diffMs / 86400000); // and you still don't have hours cleanly

// Temporal: .since() returns a Duration with the units you ask for
const start = Temporal.Instant.from("2026-07-01T09:00:00Z");
const end = Temporal.Instant.from("2026-07-16T14:30:00Z");
const elapsed = end.since(start, { largestUnit: "days" });
elapsed.toString(); // "P15DT5H30M" - 15 days, 5 hours, 30 minutes

Browser and runtime support, as of July 2026

Environment	Status
Chrome / Edge 144+	Shipped unflagged
Firefox 139+	Shipped unflagged
Safari	Not shipped, no Technology Preview yet
Node.js 26+	Shipped unflagged
Node.js 24	Behind --harmony-temporal flag

Overall browser coverage sits around 69%, and the entire gap is Safari. That means any code reaching real users still needs a polyfill today. @js-temporal/polyfill implements the full spec at about 56 KB minified and gzipped; temporal-polyfill from the FullCalendar team covers the commonly used surface at roughly 20 KB. A feature check keeps the cost near zero for users who don’t need it:

if (!globalThis.Temporal) {
  await import("temporal-polyfill/global");
}

Server-side code on Node.js 26+ needs nothing extra.

A migration strategy that doesn’t require a big-bang rewrite

Temporal and Date can coexist in the same codebase, and Temporal.Instant.fromEpochMilliseconds(date.getTime()) converts one to the other cleanly in either direction. That means you don’t need to migrate everything before shipping anything:

1. Start with the code that has caused actual bugs. DST-adjacent scheduling logic, anything doing date arithmetic across month or year boundaries, and multi-timezone display code are the highest-value targets.
2. New code gets Temporal by default. Stop adding new Date usage even before the old code is converted.
3. Convert at API boundaries. If you store timestamps as ISO strings or epoch milliseconds in a database, Temporal.Instant.from() and .toString() round-trip cleanly, so storage format doesn’t need to change.
4. Leave display formatting for last. The Intl.DateTimeFormat integration means formatting code is usually the easiest part to port, so it’s a fine place to defer.

If your team is also working through a broader modern web app stack decision this year, Temporal is worth listing as a dependency to drop rather than add: it removes date-fns or Luxon from a meaningful chunk of codebases that only pulled them in to work around exactly the problems Temporal now solves natively.

Thirty years of new Date(year, month - 1, day) footguns are optional now. Start with the file that has the most DST-related bug comments in it, and go from there.