@rikdotcodes/temporal-polyfill (Next.js 16 + Cache Components-compatible fork)

🍴 Forked from temporal-polyfill to add Next.js 16 Cache Components support (see below)

A lightweight polyfill for Temporal, successor to the JavaScript Date object

Only 20 kB, spec compliant

Fork Changes

• 0.3.2 - adds support for Next.js Cache Components. The upstream version has a bug where Temporal.Instant.from(<ISO>) will trigger a used new Date() before accessing either uncached data error during Next.js 16 pre-rendering, even though it is not actually using the current (dynamic) timestamp.
  • Upstream PR: https://github.com/fullcalendar/temporal-polyfill/pull/82

Table of Contents

• Installation
• Comparison with @js-temporal/polyfill
• Spec Compliance
• Browser Support
• BigInt Considerations
• Tree-shakable API (coming soon)

Installation

npm install @rikdotcodes/temporal-polyfill

Import as an ES module without side effects:

import { Temporal } from '@rikdotcodes/temporal-polyfill'

console.log(Temporal.Now.zonedDateTimeISO().toString())

Or, import globally:

import '@rikdotcodes/temporal-polyfill/global'

console.log(Temporal.Now.zonedDateTimeISO().toString())

~~Use a <script> tags with a CDN link:~~ unsupported for this fork

<script src='https://cdn.jsdelivr.net/npm/[email protected]/global.min.js'></script>
<script>
  console.log(Temporal.Now.zonedDateTimeISO().toString())
</script>

Comparison with @js-temporal/polyfill

Spec Compliance

All calendar systems (ex: chinese, persian) and all time zones are supported.

Compliance with the latest version of the Temporal spec is near-perfect with just 4 intentional deviations.

Browser Support

BigInt Considerations

This polyfill does NOT depend on BigInt support. Internally, no operations leverage BigInt arithmetics. :thumbsup:

However, if you plan to use methods that accept/emit BigInts, your environment must support it. Alternatively, you can avoid using these methods altogether. There's a cheatsheet to help you.

Tree-shakable API

🚧 Coming Soon

For library authors and other devs who are hyper-concerned about bundle size, temporal-polyfill will be providing an alternate API designed for tree-shaking.

import * as ZonedDateTime from 'temporal-polyfill/fns/zoneddatetime'

const zdt = ZonedDateTime.from({ year: 2024, month: 1, day: 1 })
const s = ZonedDateTime.toString(zdt) // not how you normally call a method!