temporal-polyfill

temporal-polyfill

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

Only 20 kB, spec compliant

Table of Contents

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

Installation

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/temporal-polyfill@0.3.0/global.min.js'></script>
<script>
  console.log(Temporal.Now.zonedDateTimeISO().toString())
</script>

Comparison with @js-temporal/polyfill

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

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

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)

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!

Similar packages

Other packages similar to temporal-polyfill

date-fns

date-fns is a popular library for date manipulation in JavaScript. It provides a wide range of functions for parsing, formatting, and manipulating dates. Compared to temporal-polyfill, date-fns is more focused on providing utility functions for the existing Date object, whereas temporal-polyfill introduces a new API for handling dates and times.

luxon

Luxon is a library for working with dates and times in JavaScript. It offers a more modern API compared to Moment.js and includes support for time zones and internationalization. Luxon is similar to temporal-polyfill in that it provides a new API for date and time handling, but temporal-polyfill is based on the upcoming Temporal API standard for JavaScript.

moment

Moment.js is a widely used library for date manipulation in JavaScript. It provides a comprehensive set of features for parsing, validating, manipulating, and formatting dates. However, Moment.js is considered a legacy project and is no longer actively maintained, whereas temporal-polyfill is based on the modern Temporal API.