I made another Temporal polyfill from scratch

2026-04-29T17:45:00Z

It's because existing polyfills were insufficient for me.

Brief summary

I created temporal-polyfill-lite, a lightweight Temporal polyfill.
It supports the final spec of Temporal and is compatible with the official TypeScript type definition.
For the majority of developers (those who only need the Gregorian calendar), it's the smallest Temporal polyfill available as of April 2026.

The state of ECMAScript Temporal

The Temporal proposal recently reached Stage 4. Firefox shipped it in May of last year, and Chrome followed suit this January. Node.js is planning to ship Temporal in its next major version (v26), which is set for release this May^[1]. Safari is lagging a bit behind, but implementation is underway, so it's only a matter of time^[2]. We can finally start using Temporal!

Well, we still need a polyfill for now. Until recently, there were only two polyfills: @js-temporal/polyfill and temporal-polyfill.

Existing polyfills

`@js-temporal/polyfill`

@js-temporal/polyfill is based on the reference polyfill from the Temporal proposal repository and is maintained by some of the proposal's champions. The reference polyfill itself is mainly for spec verification and doesn't aim to be production-ready, so several performance optimizations were added to make it suitable for real-world use. Sounds good so far, right?

The downside, however, is the massive bundle size: 160 kB minified and 45 kB gzipped. For comparison, the core of Moment.js is 60 kB minified and 18.5 kB gzipped. Compared to other date and time libraries, this polyfill is excessively large for frontend projects. The original code is a literal, word-for-word reference implementation of the spec and wasn't built with bundle size in mind. While it's relatively easy to optimize performance later, optimizing bundle size is much more difficult.

Moreover, while the upstream reference polyfill is actively maintained, @js-temporal/polyfill wasn't for a while. The champions always fix reported bugs quickly and reflect spec changes immediately in the proposal repository, but those changes hadn't been merged into @js-temporal/polyfill for ten months (though merging has recently resumed, e.g., js-temporal/temporal-polyfill#361). I want to clarify that I am not blaming the maintainers. Maintaining both the upstream and the fork is tough work, and the champions have a massive number of tasks to handle during the standardization process.

`temporal-polyfill`

On the other hand, temporal-polyfill has a much smaller bundle size: 57 kB minified and 20 kB gzipped. It's still a bit large but acceptable, considering the Temporal spec is over 10,000 lines long. Unfortunately, like @js-temporal/polyfill, it refers to an outdated version of the spec. Consequently, various bugs and confusing behaviors that were resolved in the final spec have remained for months (note: updates seem to be in progress now, but aren't finished yet). Some issues are rare edge cases, but others can bite anyone using Temporal in the real world. Here are a few examples:

// regular DST change:
Temporal.ZonedDateTime.from(
  "2025-11-02T01:01:00-07:00[America/Vancouver]",
).until("2025-11-02T01:00:00-08:00[America/Vancouver]", {
  largestUnit: "days",
});
// Throws `RangeError` in both polyfills,
// but should be PT59M (59 minutes) per the final spec

Temporal.PlainYearMonth.from("2024-02").subtract(
  { years: 1 },
  { overflow: "reject" },
);
// Throws `RangeError` in both polyfills,
// but should be 2023-02 (February 2023) per the final spec

In particular, era definitions for calendars were finalized relatively recently, and existing polyfills haven't caught up yet. Developers working with non-ISO calendars will likely run into trouble here:

Temporal.PlainDate.from("2026-04-01[u-ca=gregory]").era;
// Returns "gregory" in both polyfills, but "ce" per the final spec

Temporal.PlainDate.from("2026-04-01[u-ca=hebrew]").era;
// Returns undefined in both polyfills, but "am" per the final spec

temporal-polyfill also has some bugs related to time zones and date arithmetic. While bugs are inevitable, they haven't been fixed for a while, which can hinder the adoption of Temporal. For me, these were deal-breakers; I believe that reliable date arithmetic and time zone calculations are exactly the reason for being of Temporal. I didn't want to implement workarounds just because of a polyfill.

Once again, I don't want to blame the maintainer. Maintaining a Temporal polyfill is incredibly hard work (likely harder than you'd imagine), and criticizing OSS maintainers for a lack of bandwidth or time goes against the spirit of open source.

Why is it so hard to implement a polyfill?

Generally, while writing a polyfill requires specialized knowledge, it is not as hard as you might think: read the spec and implement it word for word. If you're interested in ECMAScript, writing a polyfill is usually a great place to start.

Temporal, however, is a clear exception. It's a gigantic proposal with 13,000 lines of spec text. For context, ECMA-262 (the core JS spec) is 53,000 lines, and ECMA-402 (the i18n spec) is 10,000 lines before Temporal is merged. It is the largest addition in the history of ECMAScript. Let alone implementation, even understanding the structure of such a huge spec is difficult. It requires deep knowledge of ECMA-402 and i18n, especially time zones, calendars, and Intl.DateTimeFormat, in addition to knowledge necessary for typical polyfill authors.

The options

temporal-polyfill was virtually my only option, but it had critical issues, and it seemed like nobody was working on them at the time. Literally nobody. That's understandable because not many developers have the ability, willingness, and time to fix temporal-polyfill.

I'm just a graduate student^[3] who loves web technologies; I don't belong to any standards bodies or browser vendors. However, to make a long story short, I had some knowledge of Temporal and i18n, the ability to dive into the spec, and plenty of enthusiasm for the JavaScript ecosystem. I felt like I had an obligation to do something useful instead of just posting "any updates?" comments on GitHub.

At first, I tried to fix the bugs in temporal-polyfill and sent a pull request. Unfortunately, it's been open for six months and hasn't been merged yet. I wanted to fix the remaining time zone bugs too, but I found it hard to do so while respecting the original author's architectural decisions. It would have been even harder to debate design on GitHub for me. Furthermore, the project's structure differed from the spec, making it difficult for me to track down the root cause of the arithmetic bugs. I just wasn't smart enough to map the spec text to the existing code.

Eventually, I started considering a "crazier" option: building a polyfill from scratch. It was not only because there was no other option for me. I had been curious to see how small a polyfill could be if it only supported the Gregorian calendar. I suspected that a lot of the bulk in existing polyfills came from complex non-Gregorian calendars that only a tiny fraction of developers actually need.

Requirements and design decisions

I started building temporal-polyfill-lite with a different set of design principles.

Project structure

temporal-polyfill-lite is almost a word-for-word implementation of the spec. This allows the project to benefit directly from the work of spec writers and implementers.

The spec text is extremely well-maintained pseudocode that has been reviewed and debugged by many people (including myself). Following it closely reduces bugs. It also makes debugging easier because I can compare my code directly to the reference polyfill.

If the spec text is simplified upstream, I can easily apply those simplifications to my code. Conversely, if I find a way to simplify my code, I might even be able to contribute that change back to the spec.

No protection against global namespace mutation

temporal-polyfill-lite won't work if built-in methods (like String.prototype.replace or Array.prototype.map) are deleted or modified. While this isn't strictly spec-compliant, does it really matter? If someone invasively mutates the global namespace, your entire application is going to break anyway. Protecting a polyfill from such mutations (using the "primordials" trick) sacrifices both bundle size and performance for very little practical gain.

For more on this, I recommend the excellent article "The Three Pillars of JavaScript Bloat".

Bundle size

From the start, temporal-polyfill-lite was built with bundle size as a priority. I've applied various reduction techniques throughout the codebase.

Internal representation of large integers

Temporal supports timestamps and durations with nanosecond precision. "Epoch nanoseconds" and "time durations" can exceed JavaScript's maximum safe integer (53-bit) or even a 64-bit integer.

temporal-polyfill-lite represents these large integers as an array of two numbers (a quotient and a remainder of x / 8.64e13) internally, rather than using BigInt. I borrowed this clever idea from temporal-polyfill.

Browser support

temporal-polyfill-lite works in any browser released after 2020 (it uses features from "Baseline 2020").

Since it doesn't rely on BigInt internally, it could work in older browsers if you transpile temporal-polyfill-lite and inject polyfills for APIs used internally (since code using BigInt can't be transpiled or polyfilled at all).

Time zones

temporal-polyfill-lite supports all time zones. This is definitely a long-awaited feature. Who wants to use Temporal without proper time zone support?

Calendars

By default, it only supports iso8601 and gregory calendars, which keeps the bundle small for most developers. Support for gregory is actually required if you want to format Temporal.PlainMonthDay or Temporal.PlainYearMonth using Intl.DateTimeFormat or toLocaleString, due to some quirks in those classes:

Temporal.PlainYearMonth.from("2026-04").toLocaleString("en-US", {
  dateStyle: "long",
});
// Throws a confusing "calendar mismatch" error

Temporal.PlainYearMonth.from("2026-04").toLocaleString("en-US", {
  calendar: "iso8601",
  dateStyle: "long",
});
// Returns "2026 April" in Chrome/Firefox, which isn't usually what you want
// (this format is not used in America).
// Node.js v25 returns a broken result: "2026 "

Temporal.PlainYearMonth.from("2026-04-01[u-ca=gregory]").toLocaleString(
  "en-US",
  { dateStyle: "long" },
);
// "April 2026" (exactly what you'd expect)

Implementation

It was a long, tough journey.

I started the project in June 2025, but it stalled for months because I didn't have the time to commit to it. I restarted it from zero in December 2025 (reusing many parts of the old code) and finally released the initial version in late January 2026. It took about seven weeks from the "reboot" to the first release.

Thanks to the enormous effort of the champions and implementers to expand test262, Temporal has almost 100% test coverage in test262 now. A fast test runner developed by the champions (temporal-test262-runner) was a lifesaver, significantly reducing test execution time. The Temporal proposal repository also has "thorough tests", scripts for testing implementation against a vast number of test cases. I found various bugs in my implementation with the aid of these tests.

I should mention that I was a latecomer. Unlike other polyfill authors, I implemented the polyfill based on the almost finalized spec. I didn't have to navigate the major normative changes (like the big scope reduction in June 2024) that the pioneers had to deal with. I have immense respect for those who kept their polyfills updated for years as the spec evolved.

As a side effect of building this, I found and reported several bugs and errors in the spec text and even submitted a pull request to improve it (tc39/proposal-temporal#3271). I'm very happy to have contributed to the proposal in some small way.

I know some people think human coding is obsolete. Claude Code or Codex could probably write a Temporal polyfill in days or even hours. But I wrote every line by hand, and I don't regret it. It was a "desirable difficulty" that expanded my knowledge. Understanding the details of the spec and implementation, such as how to deal with an unusual time zone transition in Canada 100 years ago or the quirks of floating-point arithmetic in JavaScript, isn't a "boring task" I want to outsource to an agent; it's exactly what I find interesting. For me, coding is like DIY and isn't something I have to "streamline" at the expense of the joy of understanding how things work^[4].

Time zone calculations

The only way to access the time zone database in JavaScript engines is by parsing the output of Intl.DateTimeFormat with the timeZone option. Parsing localized strings is usually a terrible idea, as formats vary between engines and versions, but there's no other choice. Fortunately, the formatToParts method returns structured data that is relatively reliable to parse.

new Intl.DateTimeFormat("en", {
  year: "numeric",
  month: "numeric",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  hour12: false,
  timeZone: "Asia/Tokyo",
}).formatToParts(0);
// Result:
[
  { type: "month", value: "1" },
  { type: "literal", value: "/" },
  { type: "day", value: "1" },
  { type: "literal", value: "/" },
  { type: "year", value: "1970" },
  { type: "literal", value: ", " },
  { type: "hour", value: "09" },
  { type: "literal", value: ":" },
  { type: "minute", value: "00" },
  { type: "literal", value: ":" },
  { type: "second", value: "00" },
];

Essentially, we can calculate the UTC offset by comparing the formatted parts to the original timestamp. Most date and time libraries (Luxon, Day.js with tz plugin, @date-fns/tz, etc.) and other Temporal polyfills use a similar approach too.

function getOffsetMilliseconds(epochSeconds: number, timeZone: string) {
  const parts = new Intl.DateTimeFormat("en", {
    year: "numeric",
    month: "numeric",
    day: "numeric",
    hour: "numeric",
    minute: "numeric",
    second: "numeric",
    hour12: false,
    timeZone,
  }).formatToParts(epochSeconds * 1000);
  const units = ["year", "month", "day", "hour", "minute", "second"];
  const [localYear, localMonth, localDay, localHour, localMinute, localSecond] =
    units.map((unit) => parseInt(parts.find((p) => p.type === unit)!.value));
  return (
    Date.UTC(
      localYear,
      localMonth - 1,
      localDay,
      localHour,
      localMinute,
      localSecond,
    ) -
    epochSeconds * 1000
  );
}
getOffsetMilliseconds(0, "Europe/London"); // 3600000 (UTC+1)
getOffsetMilliseconds(0, "America/New_York"); // -18000000 (UTC-5)
getOffsetMilliseconds(0, "Asia/Tokyo"); // 32400000 (UTC+9)
getOffsetMilliseconds(0, "Africa/Monrovia"); // -2670000 (UTC-0:44:30)

Because Intl.DateTimeFormat is slow, the polyfill uses an LRU cache. However, the current mechanism is far from ideal. It caches offsets for every second, even though offsets rarely change. Most countries and regions don't use DST (daylight saving time), and time zone offsets change at most twice per year in time zones where DST is observed. Time zone offset transitions for political reasons are even less common. I'm currently working on a more efficient caching algorithm (issue).

Reducing bundle size

One of my main goals was a small bundle size. I wrote a script to measure the size (with and without compression) to ensure every optimization actually worked. You can't optimize what you don't measure.

If you look at minified JavaScript code, you'll notice many long property names. That's because mangling properties is unsafe; it can easily break your code. Properties in public APIs or internal properties accessed by the bracket operator can't be mangled.

// original:
const foo = { fooBarBaz: 0 };
const prop = "fooBarBaz";
Object.keys(foo); // ["fooBarBaz"]
foo[prop]; // 0

// after mangling properties:
const foo = { a: 0 };
const prop = "fooBarBaz";
Object.keys(foo); // ["a"]
foo[prop]; // undefined

Initially, I tried to write the whole polyfill using tuples instead of objects, but that was almost impossible to maintain. No one wants to remember that isoDateTime[0][1] actually means isoDateTime.date.month. So, I decided to introduce property mangling when I "rebooted" the project.

Instead of making a long list of properties we want to preserve, I introduced a simple naming convention: every internal property that should be mangled starts with a $ (e.g., $isoDate) or _. This allows the minifier to safely mangle internal properties while leaving the public API intact. I picked up this idea from this article (English version available too) on JavaScript minification.

I also prioritized expressions over statements. Multiple function calls can be merged using the comma operator, and if statements can be converted into conditional or logical operators if the block doesn't contain any statements.

if (foo) {
  bar();
  baz();
}

// after minification:
foo && (bar(), baz());

It might seem weird to replace throw statements with function calls that throw errors, but it actually reduced the bundle size significantly because it allowed the minifier to optimize the code further. I also removed intermediate variables wherever possible to keep the code as a series of expressions.

// before:
function aaaaa(foo) {
  if (foo) {
    throw new RangeError("foo");
  }
  const bar = baz();
  return qux(bar);
}
// code above is minified like below:
function aaaaa(e) {
  if (e) throw RangeError("foo");
  let t = baz();
  return qux(t);
}

// after:
function throwRangeError(message) {
  throw RangeError(message);
}
function aaaaa(foo) {
  if (foo) {
    throwRangeError("foo");
  }
  return qux(baz());
}
// code above is minified like below:
function aaaaa(e) {
  // Note that `throwRangeError` will be also mangled in the production build.
  return (e && throwRangeError("foo"), qux(baz()));
}

Compared to the initial release, the bundle size has dropped by 15% (from 60 kB to 52 kB) minified, and 10% (from 19.7 kB to 18 kB) gzipped. What a huge win!

Support for non-Gregorian calendars

After spending a few weeks to reduce the bundle size, I became confident that the whole codebase was optimized enough. As a next step, I looked into adding non-Gregorian calendars without increasing the bundle size for the majority of users (issue). It had been in my backlog for months, but I hadn't figured out yet how to implement it.

I wanted something like Rust's feature flags, but that doesn't really exist in the JavaScript ecosystem. After human deep research and ultrathinking, I decided to use custom conditions for conditional exports and imports. Fortunately, all toolchains I use in this project (Node.js, TypeScript compiler, and Rolldown) support this.

The package.json looks like this:

{
  "exports": {
    ".": "./dist/index.js",
    "./calendars-full": "./dist/calendars/index.js"
  },
  "imports": {
    "#calendricalCalculations": {
      "nonIsoCalendars": "./src/internal/calendars/all.ts",
      "default": "./src/internal/calendars/basic.ts"
    }
  }
}

The polyfill has two entrypoints. The standard one is built without the nonIsoCalendars condition, while calendars-full includes it. Both all.ts and basic.ts export identical functions with different sets of supported calendars (see fabon-f/temporal-polyfill-lite#7 for details).

Calendrical calculations

While JavaScript engines can calculate non-Gregorian dates internally, there's no direct API to access those results (this is exactly what Temporal does). Unlike time zone calculations, parsing the output of Intl.DateTimeFormat for non-Gregorian calendars is theoretically possible but unreliable, because formats produced by Intl.DateTimeFormat for those calendars are far more inconsistent than for Gregorian across JavaScript engines or even operating systems (cf. js-temporal/temporal-polyfill#284).

Instead, I implemented the calendrical calculations myself for rule-based calendars. In particular, the hebrew calendar is purely arithmetic but incredibly complex, so I tested my implementation against ICU4X to ensure accuracy. For calendars that require astronomical simulation or historical calendar data (i.e., islamic-umalqura, persian, chinese, and dangi), the polyfill defers to the native Intl.DateTimeFormat.

The result

temporal-polyfill-lite is currently the only Temporal polyfill that follows the final spec and is compatible with the official TypeScript type definitions in v6.0. In my opinion, it's also the most reliable one for now. These points are important for developers who want to use Temporal right now, but will be irrelevant in the near future since other polyfills will eventually be updated too. I'm not sure when, but I hope so.

Instead, the real advantage of temporal-polyfill-lite is the bundle size. The table below shows the comparison as of April 2026. Note that the result can change in the future, in particular when temporal-polyfill and @js-temporal/polyfill reflect the final spec (see comparison repository for the latest result). While I'm happy with the results, I still think the calendars-full version could be a bit smaller.

	minified	gzip	brotli	zstd
native	0 kB	0 kB	0 kB	0 kB
`temporal-polyfill-lite`	52.1 kB	17.9 kB	15.9 kB	18.6 kB
`temporal-polyfill-lite/calendars-full`	63.6 kB	22.2 kB	19.6 kB	23.2 kB
`temporal-polyfill`	57.0 kB	20.3 kB	18.2 kB	21.2 kB
`@js-temporal/polyfill`	159.7 kB	45.3 kB	39.3 kB	47.2 kB

I haven't checked the runtime performance, so perhaps there is room for optimization. Of course I want to speed up the polyfill while not bloating the bundle size.

Which polyfill should we use?

I'll try to be as objective and honest as I can.

Backend projects

Introducing Temporal to backend projects sounds very reasonable and promising, because Temporal enables us to handle dates and times in a reliable manner.

You don't have to mind bundle size too much for backend. Rather, the primary requirement for these projects is robustness. I believe temporal-polyfill-lite is the best polyfill for now, but @js-temporal/polyfill would also be a good option after it is updated (I hope the update will be done in a few weeks). Both polyfills have very few bugs.

Anyway, Node.js v26 with support for Temporal will move to LTS this October, so we can remove a Temporal polyfill from backend projects soon.

Frontend projects

Honestly, it would be too early to use Temporal for most frontend projects since it isn't even "Baseline Newly available" yet and a Temporal polyfill isn't tiny. However, Temporal is no longer unstable or experimental, so you can try it. In particular, projects using SSG frameworks such as Astro can benefit from Temporal without increasing JavaScript size.

In my opinion, temporal-polyfill-lite is the least painful polyfill for frontend projects, because it is up-to-date, least buggy, and the smallest for most developers, at least for now. temporal-polyfill can be another option after it is fixed and updated.

Conclusion

I've been following the Temporal proposal for the last two years, always wondering when it would be ready for production. Now I can answer that question with confidence: you can use it today if you really want. If you want to start using Temporal right now, temporal-polyfill-lite is exactly what you need for the foreseeable future (for a few years at most, I believe).

If you find any bugs, please feel free to report them on GitHub. I'll fix them as soon as possible.

In closing, it's a great honor to contribute to Temporal, the unparalleled project in the history of ECMAScript. Long live web standards! Long live ECMAScript!

The release is originally planned in 22nd April, but it has been postponed until 4th May due to build issues, mainly caused by Temporal implementation. V8 introduced Rust dependencies (ICU4X and temporal_rs) for the first time to implement Temporal (cf. nodejs/node#58730), therefore Node.js have to add Rust toolchains to build pipeline. The work is basically done, but Node.js developers are still struggling with build errors. ↩︎
I agree about the part that it's a matter of time, but I can't say irresponsibly that Safari will ship Temporal soon. Honestly, I think it can't happen in this year. There is still great uncertainty, especially problems of calendrical calculations in ICU4C. I even suspect communication between Igalia and Apple doesn't work well, or implementation of Temporal has low priority, but I hope I'm wrong. ↩︎
Actually, I'm not even a STEM student. I'm currently studying modern Russian history at the University of Tokyo. ↩︎
That being said, I'm still exploring how to integrate coding agents into my workflow without losing the parts of coding I find fun. ↩︎

fabon's blog