Migrating a Node library from polyfilled `Temporal` to Node 26 native `Temporal`

Cna — Wed, 19 Aug 2026 12:56:55 +0000

Without breaking Node 24, CJS, or TypeScript 6/7.

Node 26 enabled native Temporal by default on 2026-05-05. Node 24 LTS is
supported until April 2028. If you publish a library, both are your users at the
same time, and they will be for years.

This guide is for library authors. If you ship an application and control
your own Node version, your migration is one line — drop the polyfill when you
move to Node 26 — and you can stop reading.

The three things that actually break

Most migration advice says "the polyfill and native Temporal are
spec-compatible, so just swap them". That is true about behaviour and false about
identity. Three concrete failures:

1. `instanceof` stops working

foreignZdt instanceof Temporal.ZonedDateTime; // false

The value is a perfectly valid ZonedDateTime. It just came from a different
implementation, so it has a different prototype chain. Any guard, any router, any
switch built on instanceof silently takes the wrong branch.

2. Some values are rejected outright

Passing a foreign value into a Temporal API falls back to reading it as a
property bag. For most types that quietly works. For ZonedDateTime it does not:

Temporal.ZonedDateTime.compare(foreignZdt, mine);
// TypeError: Missing timeZone

@js-temporal/polyfill exposes timeZoneId, not timeZone, so the property-bag
path finds nothing to read. This is a hard failure at runtime, in production, on
a mixed-version fleet — and it is exactly what
Fedify hit.

Borrowed methods fail too:

Temporal.PlainDate.prototype.add.call(foreignDate, { days: 1 });
// TypeError: Invalid calling context

3. Your public types are tied to one implementation

import type { Temporal } from "@js-temporal/polyfill";
export function schedule(when: Temporal.ZonedDateTime): void;

That signature describes that polyfill's classes. A caller on Node 26 holding a
native ZonedDateTime may not satisfy it, and on TypeScript 6 the two
declarations
conflict outright.

There is a fourth trap that only bites CJS users — covered in step 4.

Step 1 — Stop importing types from an implementation

Take your public types from a types-only package that describes the spec
rather than a class hierarchy.
temporal-spec is derived from
TypeScript's own esnext.intl.d.ts, so it is the same shape the built-in lib
uses for native Temporal.

- import type { Temporal } from "@js-temporal/polyfill";
+ import type { Temporal } from "temporal-spec";

  export function schedule(when: Temporal.ZonedDateTime): void;

Now a native value, a temporal-polyfill value and a @js-temporal/polyfill
value all satisfy the signature.

If you use temporal-gregorian, re-export it from there instead so your
consumers need no extra dependency:

import type { Temporal } from "temporal-gregorian/types";

Verify it. Write a fixture that pushes values both directions across the
line and type-check it under every TypeScript version you support:

declare const nativeZdt: Temporal.ZonedDateTime; // what Node 26 hands you
declare function takesNative(v: Temporal.ZonedDateTime): void;

takesNative(myLibrary.build());   // ours -> native-typed slot
myLibrary.schedule(nativeZdt);    // native -> ours

Run it under moduleResolution: NodeNext and Bundler. They resolve
declarations differently and a package can pass one while failing the other.

Step 2 — Delete every `instanceof` check

Replace them with a check on Symbol.toStringTag, which every Temporal value
carries and every implementation sets identically:

- if (value instanceof Temporal.ZonedDateTime) { ... }
+ if (getTemporalType(value) === "ZonedDateTime") { ... }

Rolling your own is ~6 lines:

export function getTemporalType(value) {
  if (value === null || typeof value !== "object") return undefined;
  const tag = value[Symbol.toStringTag];
  if (typeof tag !== "string" || !tag.startsWith("Temporal.")) return undefined;
  return tag.slice("Temporal.".length);
}

Note the caveat: Symbol.toStringTag is an ordinary forgeable property. It is
the right tool for telling apart values you already trust, not for validating
untrusted input. Step 3 closes that gap.

Step 3 — Normalize values at your API boundary

Detecting a foreign value is not enough — you still have to use it. Rebuild it
with whichever implementation is active in your process:

import { normalizeTemporal, getTemporalType } from "temporal-gregorian";

export function schedule(when) {
  if (getTemporalType(when) !== "ZonedDateTime") {
    throw new TypeError("schedule() needs a Temporal.ZonedDateTime");
  }
  const zdt = normalizeTemporal(when); // returns `when` unchanged if already ours
  return zdt.add({ hours: 1 });        // safe
}

Doing it by hand, the two rules that matter:

Exact time crosses as a BigInt, not a string. epochNanoseconds is a primitive, so it is implementation-independent and cannot lose precision.
Rebuild ZonedDateTime from (epochNanoseconds, timeZoneId, calendarId), not from its offset string. If the two implementations carry different tzdata versions, re-parsing an offset can move the instant or throw. Pinning the epoch value cannot.

Everything else round-trips losslessly through toString(), which carries full
nanosecond precision plus the calendar and time-zone annotations.

Normalize once, at the boundary — not on every internal call. Inside your
library the values are already yours.

Step 4 — Do not break CJS

This is the step most migrations miss.

temporal-polyfill publishes no require condition in its exports. So:

require("temporal-polyfill"); // Node 18, Node 20.0-20.18:
// Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported

It works on Node 20.19+, 22.12+, 24 and 26 (which support require(esm)), and
fails below that. If your library is dual-published and any consumer is on Node
18, a plain dependency on temporal-polyfill breaks them.

Three ways out, in order of preference:

Bundle the polyfill into your CJS build only. ESM keeps it external so consumers share one copy; CJS inlines it so require() works everywhere. This is what temporal-gregorian does — see its tsup.config.ts.
Raise your engines floor to >=20.19 and keep the dependency external. Simpler, but it is a breaking change for your Node 18 users.
Stay on @js-temporal/polyfill, which ships a real CJS build — at roughly 2.4× the bundle size (~46.9 KB vs ~19.7 KB min+gzip) and with the type problem from step 1 still unsolved.

Bundling has one cost, and you should know it: a CJS consumer who also installs
the polyfill directly ends up with two copies, which is precisely the foreign-value
situation from step 3. That is why step 3 comes first.

Step 5 — Prove it with a matrix, not with a smoke test

Importing your package once on your laptop proves nothing here. The failures are
combinational. Test the packed tarball — not your source tree — across:

Axis	Values
Node	18, 20, 22, 24, 26
Module format	ESM, CJS
Runtime	native `Temporal`, polyfilled `Temporal`
TypeScript	5.9, 6.0, 7.0
Module resolution	`NodeNext`, `Bundler`
Interop	a value from another implementation crossing your API

You do not need Node 26 runners to test the native path. Install
globalThis.Temporal before your package loads and any Node 18+ process behaves
like a native one:

// simulate-native.mjs — load with: node --import ./simulate-native.mjs app.mjs
import { Temporal } from "temporal-polyfill/implementation";
globalThis.Temporal = Temporal;

In ESM this must live in its own module, imported first. Every import's body
runs before the importing module's own statements, so an inline assignment lands
after your package has already read the global.

Working implementations of both matrices:
scripts/compat-matrix.mjs and
scripts/check-type-resolution.mjs.

Step 6 — Let the runtime pick

Once the above is in place, the actual "migration" is nothing. Feature-detect at
load and pass through:

const Temporal = globalThis.Temporal ?? polyfillTemporal;

temporal-polyfill already does this internally, and so does
temporal-gregorian. Your Node 26 users get native Temporal at zero overhead
the day they upgrade; your Node 24 users notice nothing; and neither can hand the
other a value your library chokes on.

See it fail, then see it work

git clone https://github.com/sina-heidariaan/temporal-gregorian
cd temporal-gregorian
npm ci && npm run build

npm run demo          # polyfilled runtime
npm run demo:native   # simulated Node 26 native runtime

Source: examples/mixed-runtime/demo.mjs.

Checklist

[ ] Public types come from temporal-spec (or temporal-gregorian/types), not from a polyfill package.
[ ] Zero instanceof checks against Temporal classes.
[ ] Foreign values are normalized once, at the API boundary.
[ ] ZonedDateTime is rebuilt from epochNanoseconds, not from an offset string.
[ ] require() works on your lowest supported Node.
[ ] CI covers Node × format × runtime × TypeScript × module resolution.
[ ] The native path is tested, even without a Node 26 runner.

Found a case this guide misses, or a combination that still breaks? Please open an issue at temporal-gregorian/issues
— real-world interop reports are what this package is for.

DEV Community: Cna