# temporal-polyfill > A lightweight polyfill for Temporal, successor to the JavaScript Date object Latest version **1.0.5** (published 2026-09-11) · MIT license · 0 weekly downloads ## Install ```sh npm install temporal-polyfill pnpm add temporal-polyfill yarn add temporal-polyfill bun add temporal-polyfill ``` ## Health **Score 65/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 1.0.5 | | Published | 2026-09-11 | | First published | 2021-05-19 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 2 | | Unpacked size | 1005 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 775 | | Author | Adam Shaw | | Maintainers | arshaw | ## Links - npm: https://www.npmjs.com/package/temporal-polyfill - Repository: https://github.com/fullcalendar/temporal-polyfill - Homepage: https://github.com/fullcalendar/temporal-polyfill#readme - Issues: https://github.com/fullcalendar/temporal-polyfill/issues - npm.io page: https://npm.io/package/temporal-polyfill ## Dependencies (2) - [temporal-spec](https://npm.io/package/temporal-spec.md) 1.0.1 - [temporal-utils](https://npm.io/package/temporal-utils.md) 1.0.3 ## Recent versions - 1.0.5 (latest) — 2026-09-11 - 0.3.0-beta.1 (beta) — 2025-03-12 - 1.0.4 — 2026-08-13 - 1.0.3 — 2026-08-03 - 1.0.2 — 2026-07-27 - 1.0.1 — 2026-06-19 - 0.3.2 — 2026-03-10 - 0.3.1 — 2026-03-10 - 0.3.0 — 2025-03-28 - 0.3.0-beta — 2025-03-11 - 0.2.5 — 2024-05-31 - 0.2.4 — 2024-04-06 - 0.2.3 — 2024-03-01 - 0.2.2 — 2024-02-21 - 0.2.1 — 2024-02-06 - … 12 more at https://npm.io/package/temporal-polyfill/versions ## README # temporal-polyfill A lightweight polyfill for [Temporal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal), successor to the JavaScript `Date` object 🕒 Only 19.5 kB and [spec compliant](#spec-compliance) 🌳 Need an even smaller footprint? Check out the [tree-shakeable API](https://github.com/fullcalendar/temporal-polyfill/blob/main/docs/fns/index.md) ## Table of Contents - [Installation](#installation) - [Package Entrypoints](#package-entrypoints) - [CDN Usage](#cdn-usage) - [Global TypeScript Types](#global-typescript-types) - [Spec Compliance](#spec-compliance) - [Supported Environments](#supported-environments) - [Comparison with `@js-temporal/polyfill`](#comparison-with-js-temporalpolyfill) - [Tree-shakeable API](#tree-shakeable-api) ## Installation ``` npm install temporal-polyfill ``` ```js import 'temporal-polyfill/global' // most common entrypoint ``` Or learn about [CDN usage](#cdn-usage) ## Package Entrypoints The following entrypoints support the `iso8601` and `gregory` calendar systems only: - Global polyfill. Uses native if available. 👈 **What most people need** ```js import 'temporal-polyfill/global' Temporal.Now.zonedDateTimeISO().toString() ``` - Local side-effect-free import (ponyfill). Uses native if available ```js import { Temporal } from 'temporal-polyfill' Temporal.Now.zonedDateTimeISO().toString() ``` - Forced non-native side-effect-free import ```js import { Temporal } from 'temporal-polyfill/implementation' Temporal.Now.zonedDateTimeISO().toString() ``` - Install the global polyfill *when* you want ```js import { install } from 'temporal-polyfill/shim' install() // uses native if available Temporal.Now.zonedDateTimeISO().toString() ``` - Install the non-native implementation globally based on a custom condition ```js import { installImplementation } from 'temporal-polyfill/shim' if (!globalThis.Temporal || CUSTOM_CONDITION) { installImplementation() } Temporal.Now.zonedDateTimeISO().toString() ``` The `/full/` entrypoints support an expanded set of calendar systems: `buddhist`, `chinese`, `coptic`, `dangi`, `ethiopic`, `ethioaa`, `hebrew`, `indian`, `islamic-civil`, `islamic-tbla`, `islamic-umalqura`, `japanese`, `persian`, and `roc`. - Global polyfill. Uses native if available ```js import 'temporal-polyfill/full/global' Temporal.Now.zonedDateTimeISO().withCalendar('buddhist').toString() ``` - Local side-effect-free import (ponyfill). Uses native if available ```js import { Temporal } from 'temporal-polyfill/full' Temporal.Now.zonedDateTimeISO().withCalendar('buddhist').toString() ``` - Forced non-native side-effect-free import ```js import { Temporal } from 'temporal-polyfill/full/implementation' Temporal.Now.zonedDateTimeISO().withCalendar('buddhist').toString() ``` - Install the global polyfill *when* you want ```js import { install } from 'temporal-polyfill/full/shim' install() // uses native if available Temporal.Now.zonedDateTimeISO().withCalendar('buddhist').toString() ``` - Install the non-native implementation globally based on a custom condition ```js import { installImplementation } from 'temporal-polyfill/full/shim' if (!globalThis.Temporal || CUSTOM_CONDITION) { installImplementation() } Temporal.Now.zonedDateTimeISO().withCalendar('buddhist').toString() ``` ## CDN Usage Globally install the polyfill that supports only the `iso8601` and `gregory` calendar systems. Uses native if available. ```html ``` Globally install the `/full/` polyfill that supports an expanded set of calendar systems: `buddhist`, `chinese`, `coptic`, `dangi`, `ethiopic`, `ethioaa`, `hebrew`, `indian`, `islamic-civil`, `islamic-tbla`, `islamic-umalqura`, `japanese`, `persian`, and `roc`. ```html ``` ## Global TypeScript Types If using the `temporal-polyfill/global` or `temporal-polyfill/full/global` entrypoints, you must configure types: ### If using TypeScript >= 6.0 In your `tsconfig.json`: ```diff { "compilerOptions": { + "lib": ["esnext"] } } ``` Or with more granularity: ```diff { "compilerOptions": { + "lib": ["esnext.temporal", "esnext.intl", "esnext.date"] } } ``` ### If using TypeScript < 6.0 Write an ESM import that loads the types: ```diff import 'temporal-polyfill/global' + import 'temporal-polyfill/types/global' console.log(Temporal.Now.zonedDateTimeISO().toString()) ``` ## Spec Compliance All time zones are supported. The following calendar systems are supported: `buddhist`, `chinese`, `coptic`, `dangi`, `ethiopic`, `ethioaa`, `hebrew`, `indian`, `islamic-civil`, `islamic-tbla`, `islamic-umalqura`, `japanese`, `persian`, and `roc`. Compliance with the latest version of the Temporal spec is near-perfect [with just 2 intentional deviations](https://github.com/fullcalendar/temporal-polyfill/blob/main/polyfill/scripts/test262-expected-failures/shim.txt). ## Supported Environments | Browser | Minimum Release | For `chinese`, `dangi`, `islamic-umalqura`\* | | :--------- | --------------: | -------------------------------------------: | | Chrome | 67 (May 2018) | 80 (Feb 2020) | | Firefox | 68 (Jul 2019) | 76 (May 2020) | | Safari | 14 (Sep 2020) | 14.1 (Apr 2021) | | Safari iOS | 14 (Sep 2020) | 14.5 (Apr 2021) | | Edge | 79 (Jan 2020) | 80 (Feb 2020) | Node.js is supported down to version 16 (Released Apr 2021, EOL since Sep 2023). [CI](https://github.com/fullcalendar/temporal-polyfill/blob/main/.github/workflows/ci.yml) runs the full test suite against Node 16, 18, 20, 22, 24, and 26. \* On Android, Chrome's `Intl.DateTimeFormat` API formats some `islamic-umalqura` dates incorrectly ([Chromium issue](https://issues.chromium.org/issues/40856332)), but the `Temporal` API itself is unaffected. Patching `Intl.DateTimeFormat` is out of scope for this polyfill. ## 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
Min+gzip size 19.4 kB, 23.3 kB (full) 52.1 kB (+168%, +124%)
Spec date September 2026 March 2025
BigInt approach Uses real bigint sparingly Internally relies on JSBI
Global install Possible via ESM and CDN Not currently possible
## Tree-shakeable API 🌳 For anyone hyper-concerned about bundle size, `temporal-polyfill` also ships an alternate function API designed for tree-shaking. Instead of large `Temporal.*` classes, every operation is a standalone function that acts on a plain record, so a bundler keeps only the functions you actually import. ```js import * as PlainDateFns from 'temporal-polyfill/fns/PlainDate' const date = PlainDateFns.create(2026, 6, 1) const later = PlainDateFns.addMonths(date, 2) PlainDateFns.toString(later) // '2026-08-01' ``` 🤝 **Building a component library?** The function API is built to be a shared, deletable peer dependency for third-party tools like date pickers and schedulers. See [For component authors](https://github.com/fullcalendar/temporal-polyfill/blob/main/docs/fns/for-component-authors.md). Each Temporal type has its own entrypoint under `temporal-polyfill/fns/*` — for example `temporal-polyfill/fns/PlainDate` or `temporal-polyfill/fns/ZonedDateTime`. Best of all, this isn't a one-way door. When the time is right — once native `Temporal` is available in every environment you target, and you no longer need the polyfill — [temporal-polyfill-codemod](https://github.com/fullcalendar/temporal-polyfill/blob/main/codemod/README.md) rewrites your function calls back into idiomatic `Temporal.*` expressions. So `PlainDateFns.addMonths(date, 2)` becomes `date.add({ months: 2 })`, with no manual find-and-replace. 📖 [**Read the full Tree-shakeable API docs →**](https://github.com/fullcalendar/temporal-polyfill/blob/main/docs/fns/index.md) The docs cover the complete catalog of functions, their TypeScript type exports, the codemod workflow, and how each function maps back to the standard `Temporal` API. --- _Source: https://npm.io/package/temporal-polyfill · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._