How would you introduce Temporal into a large existing JavaScript codebase that uses the built-in Date everywhere, given that Temporal is still a proposal and ships unevenly?

## Frame the decision honestly Temporal is not free. As a Stage 3 TC39 proposal it is not yet universally available in shipped engines: Firefox enabled it by default in 2025, other engines are in progress, and until that spreads, production code depends on `@js-temporal/polyfill`, which is a non-trivial addition to a browser bundle. So the first thing a lead owes the team is a reason. "Modern API" is not one. The reason is that `Date` conflates an instant with a wall-clock reading, mutates in place, and has no notion of a time zone beyond the host's, and those properties generate a specific, recurring class of defects. If your product does no zone-aware or calendar arithmetic, the honest answer may be "not yet". ## Interop is the enabling fact A gradual migration is only viable because the two representations convert cheaply and losslessly through the epoch: ```js const d = new Date(); const instant = Temporal.Instant.fromEpochMilliseconds(d.getTime()); const back = new Date(instant.epochMilliseconds); ``` Nothing is lost in either direction at millisecond precision, which is all a `Date` has. That means Temporal can be adopted module by module without a flag day: a function can accept a `Date`, convert on entry, compute in Temporal, and convert back on return. Callers see no change. ## Sequence by risk, not by file count Rank the code by what a `Date` bug there actually costs. **Move first:** scheduling and recurrence, billing and subscription periods, anything doing "same time tomorrow" or "the first of next month", and anything that renders a time in a zone other than the server's. This is where the conflation bites, and where `ZonedDateTime` arithmetic and the explicit `disambiguation` option pay for themselves immediately. **Move next:** date-only values — birth dates, invoice dates, effective dates. Modelling these as `Temporal.PlainDate` removes the entire family of off-by-one-day bugs caused by a date-only value acquiring a midnight that then shifts across a zone boundary. **Move last, or never:** timestamps that are only compared, sorted, or logged. A `Date` used purely as an epoch number is not wrong, just unexpressive. Rewriting it buys little and costs review time. ## Fix the boundaries first Before converting internals, decide the storage and wire formats, because those outlive the code. Establish that exact times persist as `Z`-suffixed ISO strings or epoch values, date-only fields persist as `YYYY-MM-DD`, and future local events persist as a wall-clock value plus an IANA zone ID. Once the boundary shapes are right, the internal type can change under them without another migration. Doing it in the other order means migrating twice. Serialization is direct: every Temporal type has `toJSON()`, so `JSON.stringify` produces the ISO form automatically. The reverse is not automatic — a parsed object is a string until you call `Temporal.Instant.from(...)`, `Temporal.PlainDate.from(...)` and so on. Centralise that reconstruction in your deserialisation layer rather than scattering `from()` calls. ## Warn the team about three behaviours First, **`valueOf` throws.** Every Temporal type deliberately throws a `TypeError` from `valueOf()`, so `a - b`, `a < b` and `a > b` fail loudly instead of quietly comparing strings. This is a feature — it catches exactly the code that would have been wrong — but a team converting a module will hit it immediately and should know the replacements are `Temporal.X.compare(a, b)` and `a.until(b, { largestUnit })`. The good news is that these are runtime failures at the offending line, not silent drift. Second, **immutability changes call shape.** `d.add({ days: 1 })` returns a value and mutates nothing, so a mechanical translation of a mutating `setDate` call that discards the result runs fine and does nothing. Third, **types no longer interchange.** A function that previously took "a date" now takes a `PlainDate` or a `ZonedDateTime`, and mixing them is an error rather than an implicit conversion. That friction is the point, but it means signatures need deciding rather than defaulting. ## Keep it from stalling half-done The failure mode of every gradual migration is an indefinite middle state where both representations circulate and nobody knows which a given function expects. Guard against it: name the boundary modules where conversion is allowed and forbid it elsewhere in review, keep one utility that does the `Date` interop so the conversion sites are greppable, and set a policy that new code is Temporal-only from a chosen date. If your codebase already carries a third date library, fold that into the same effort rather than adding a fourth representation. Finally, decide up front what "done" means and whether it includes dropping the polyfill once engine support is broad, because that is the point where the bundle cost you accepted is repaid.