A lightweight polyfill for Temporal, successor to the JavaScript Date object
npm install temporal-polyfillA 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:
`js
import { Temporal } from 'temporal-polyfill'
console.log(Temporal.Now.zonedDateTimeISO().toString())
`
Or, import globally:
`js
import 'temporal-polyfill/global'
console.log(Temporal.Now.zonedDateTimeISO().toString())
`
Use a
`
| 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. :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.
š§ 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.
`js
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!
``