A lightweight polyfill for Temporal, successor to the JavaScript Date object
Only 20 kB, spec compliant
- Installation
- Comparison with
@js-temporal/polyfill - Spec Compliance
- Browser Support
- BigInt Considerations
- Tree-shakable API (coming soon)
npm install temporal-polyfill
Import as an ES module without side effects:
import { Temporal } from 'temporal-polyfill'
console.log(Temporal.Now.zonedDateTimeISO().toString())Or, import globally:
import 'temporal-polyfill/global'
console.log(Temporal.Now.zonedDateTimeISO().toString())Use a <script> tags with a CDN link:
<script src='https://cdn.jsdelivr.net/npm/[email protected]/global.min.js'></script>
<script>
console.log(Temporal.Now.zonedDateTimeISO().toString())
</script>| Package |
temporal-polyfill
|
@js-temporal/polyfill
|
| Repo | fullcalendar/temporal-polyfill | js-temporal/temporal-polyfill |
| Creators | FullCalendar lead dev arshaw | Champions of the Temporal proposal |
| Minified+gzip size | 19.8 KB | 51.9 KB (+162%) |
| Spec date | Mar 2025 | Mar 2025 |
| BigInt approach | Internally avoids BigInt operations altogether | Internally relies on JSBI |
| Global usage in ESM |
import 'temporal-polyfill/global'
|
Not currently possible |
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.
| Minimum required browsers for ISO/gregory calendars: | |||||
| Chrome 60 (Jul 2017) |
Firefox 55 (Aug 2017) |
Safari 11.1 (Mar 2018) |
Safari iOS 11.3 (Mar 2018) |
Edge 79 (Jan 2020) |
Node.js 14 (Apr 2020) |
|
If you transpile, you can support older browsers down to: |
|||||
| Chrome 57 (Mar 2017) |
Firefox 52 (Mar 2017) |
Safari 10 (Sep 2016) |
Safari iOS 10 (Sep 2016) |
Edge 15 (Apr 2017) |
Node.js 14 (Apr 2020) |
|
For non-ISO/gregory calendars, requirements are higher: |
|||||
| Chrome 80 (Feb 2020) |
Firefox 76 (May 2020) |
Safari 14.1 (Apr 2021) |
Safari iOS 14.5 (Apr 2021) |
Edge 80 (Feb 2020) |
Node.js 14 (Apr 2020) |
This polyfill does NOT depend on BigInt support. Internally, no operations leverage BigInt arithmetics. 👍
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.
🚧 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!