# tc39/proposal-temporal: the Temporal API, now Stage 4 and shipping in browsers > Temporal replaces JavaScript's Date with immutable calendar-aware types. The proposal reached Stage 4, Firefox, Chrome and Node have shipped it, and the repository's own polyfill is explicitly not for production use. **tc39/proposal-temporal** — Provides standard objects and functions for working with dates and times. - Repository: https://github.com/tc39/proposal-temporal - Website: https://tc39.es/proposal-temporal/docs/ - Stars: 3,707 · Forks: 175 - Language: HTML - License: NOASSERTION - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/tc39-proposal-temporal ## The problem Temporal solves, and who it is written for JavaScript's Date has been a long-standing pain point in ECMAScript, and the README links to a post titled "Fixing JavaScript Date" for the full argument. The practical audience is anyone who computes with dates rather than merely displaying them: scheduling tools, billing systems, calendar UIs, and libraries that currently carry their own date arithmetic because Date cannot express it. Temporal is proposed as a global Object that acts as a top-level namespace, like Math, so it does not require an import or a module dependency once the engine ships it. The design constraints matter more than the type list. All Temporal objects are immutable. Date values can be represented in local calendar systems but must be convertible to and from the Proleptic Gregorian Calendar. Time-of-day values use a standard 24-hour clock, and leap seconds are not represented. That last point is a deliberate exclusion, not an oversight, and it tells you the target is civil timekeeping rather than astronomy or high-precision timing. ## How the proposal is structured, and where the polyfill sits This repository is not a library you install. It holds spec.html, the spec/ directory, docs/, meetings/, and a polyfill/ directory. The package.json is marked "private": true and its scripts orchestrate testing and building rather than publishing: test runs the polyfill tests, the cookbook tests and test262; build chains build:polyfill, build:docs and build:spec; build:spec runs ecmarkup against the ECMA-262 and ECMA-402 bibliographies. The main field points at polyfill/lib/index.mjs, which is the entry point for the in-repo implementation, not a package name you would add to a project. The README is blunt about that polyfill: it was built to validate the proposal, it continues to live in the repo only for running tests and powering the documentation playground, and the README says in capitals not to use it in your own projects. Instead it points at a table of three third-party polyfills: @js-temporal/polyfill (alpha release available), temporal-polyfill from fullcalendar (stable release available), and temporal-polyfill-lite (release candidate available). That table is the real adoption path for anyone on an engine without native support. ## Installing it and a first real use On a runtime that already ships Temporal, there is nothing to install. The README's implementation status list records SpiderMonkey/Firefox as shipped in Firefox 139 on 2025-05-27, V8/Chrome as shipped in Chrome 144 on 2026-01-13, and Node.js as shipped in Node 26 on 2026-05-05. If you are on one of those, the global Temporal object is simply present. For older runtimes, the README's polyfill table is the place to start. It lists the npm package name and the repository for each entry, and marks temporal-polyfill as a stable release. The README does not give install commands for any of them, so the package names in that table are the only concrete identifiers to work from. The documentation playground is the fastest way to see the API without installing anything. When you open the reference documentation at tc39.es/proposal-temporal/docs/index.html, the README states that the non-production polyfill is automatically loaded in your browser, so you can try Temporal by opening the developer tools console. There is also a cookbook linked from the README for worked examples, and the docs are available in English, Japanese and Chinese translations. What to expect from the API shape: Temporal is a namespace, not a constructor you call directly. The related searches that people run against this project include "Temporal PlainDate", which names one of the types in that namespace, and the docs index is where the full set is enumerated. The README itself does not list the types, so read the reference documentation rather than guessing names from the proposal title. ## Where Temporal is the wrong tool Leap seconds are not represented. If your domain needs them, this API will not give you what you want, and no amount of polyfilling changes that, because the exclusion is in the principles section of the README rather than in an implementation detail. Safari is the obvious gap. The README's status list shows JavaScriptCore/Safari as a bug link with no shipped marker, alongside Boa and Kiesel, and GraalJS as planned to ship in GraalVM 25.1.0. If your support matrix includes Safari and you cannot ship a polyfill, you are not ready to depend on native Temporal alone. The README does not state a Safari timeline. The repository is also the wrong dependency for a different reason. It is a specification repository. Its package.json is private, its test script installs and runs the polyfill's own suite, and the README instructs you not to use the bundled polyfill. Cloning this to get Temporal into an application is a misreading of what the repo is for. ## Alternatives, and how they differ in approach The most direct alternative is to keep using Date and a helper library. That is a different architecture, not a different implementation: you inherit a mutable object, you carry the timezone and calendar logic in userland, and every library in your stack has to agree on the same conventions. Temporal moves those conventions into the language so that two libraries cannot disagree about them. Within the Temporal world, the choice is between native support and one of the three polyfills in the README's table. They are not equivalent. @js-temporal/polyfill is listed as an alpha release, temporal-polyfill as a stable release, and temporal-polyfill-lite as a release candidate. The lite variant's name signals a smaller surface, which is a trade-off you would have to read its own repository to evaluate; the README here does not describe what any of the three omit. A third option is to wait. Because the proposal is Stage 4 and the README states it will be merged into ECMA-262 and ECMA-402, with this repository then archived, the eventual default is native support with no dependency at all. That is a legitimate position for code that does not need the API yet. ## Maintenance, licence and upgrade cost The repository is not archived, and the last push was on 2026-07-27. That is the state to plan against: the proposal is done and the repository's remaining job is to hold the spec text, the docs and the test harness until the merge lands. The README states the repository will be archived once the proposal is merged into ECMA-262 and ECMA-402, so any tooling you build against this repo's layout has a known expiry. The licence field is NOASSERTION, which means the repository's LICENSE file is the only reliable source for terms. Read it before you reuse spec text, documentation or polyfill code, and note that the three polyfills in the README's table are separate projects with their own licences. Nothing here is legal advice; the point is that the licence identifier on the repository listing does not tell you the terms. Upgrade cost is asymmetric. If you adopt a polyfill today, you are paying a bundle-size and maintenance cost that disappears when your target runtimes ship native support, and the README's status table gives you the dates to plan that removal against for Firefox, Chrome and Node. If you adopt native Temporal, your cost is the minimum engine version, and the README's engines field ("node": ">=12.16.0") describes the tooling in this repo, not a requirement for the API itself. ## Conclusion Adopt Temporal directly if you target Firefox 139 or later, Chrome 144 or later, or Node 26 or later, and reach for the stable temporal-polyfill from the README's table when you need older runtimes. Do not adopt the polyfill directory inside this repository: the README says it is non-production and exists for tests and the documentation playground. Before committing, check the specification text at tc39.es/proposal-temporal for the exact behaviour of the types you plan to use, and confirm Safari's JavaScriptCore status separately, because the README lists that bug as open with no ship date. ## FAQ ### What is the JavaScript Temporal API? It is a Stage 4 proposal for a global Object called Temporal, acting as a top-level namespace like Math, that brings a modern date and time API to ECMAScript. Its principles state that all Temporal objects are immutable, that date values can use local calendar systems while remaining convertible to and from the Proleptic Gregorian Calendar, that time-of-day values use a 24-hour clock, and that leap seconds are not represented. ### Can I use the Temporal API in browsers and Node today? The README's implementation status list records Temporal as shipped in Firefox 139 on 2025-05-27, in Chrome 144 on 2026-01-13, and in Node 26 on 2026-05-05. JavaScriptCore/Safari, Boa and Kiesel are listed without a shipped marker, and GraalJS is listed as planned to ship in GraalVM 25.1.0. ### What are temporal dates in the tc39/proposal-temporal sense? They are the date and time values produced by the Temporal namespace, where every object is immutable and time-of-day values are based on a standard 24-hour clock. The README notes that date values can be represented in local calendar systems but should be convertible to and from the Proleptic Gregorian Calendar, and that leap seconds are not represented. ## Sources - [Issues](https://github.com/tc39/proposal-temporal/issues) - [Project website](https://tc39.es/proposal-temporal/docs/) - [README](https://github.com/tc39/proposal-temporal/blob/main/README.md) - [Releases](https://github.com/tc39/proposal-temporal/releases) - [tc39/proposal-temporal on GitHub](https://github.com/tc39/proposal-temporal) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tc39-proposal-temporal