proposal-temporal is finished work that still tells you not to use its own polyfill

Stage 4 means this repository is scheduled to be archived

The status section is short and decisive. The proposal is at Stage 4, which is the final stage, and it will be merged into the ECMA-262 and ECMA-402 standards. The same paragraph states the consequence for the repository itself: it will be archived once that merge happens. So what is here is the specification record, not an actively developed library, and the tests, meetings and build tooling exist to finish and validate a proposal rather than to ship a product. The rendered specification lives at tc39.es/proposal-temporal/ and the reference documentation at the docs path under the same host, which is why the documentation address appears as the homepage field. The single release the repository ever published is version 0.1.0, described as the initial release of the proposal polyfill and dated 2020-06-15, while the manifest itself sits at version 1.0.0 and is marked private.

Three engines have shipped it and four trackers are still open

The implementation list is organised by engine and mixes finished work with open issues. SpiderMonkey shipped it in Firefox 139 on 2025-05-27. V8 shipped it in Chrome 144 on 2026-01-13. Node.js shipped it in Node 26 on 2026-05-05. Four entries have no shipped date: JavaScriptCore carries a WebKit bug, Boa carries a GitHub issue, and Kiesel carries a Codeberg issue. GraalJS is the only one with a stated plan, marked as planned to ship in GraalVM 25.1.0. So the practical answer to whether you can use Temporal today depends on your runtime rather than on the proposal: on the three shipping engines you can call it directly, and on the others you are reading an issue tracker. Nothing in the list mentions embedding it in a non browser runtime beyond Node.

Four design principles, and leap seconds are the one left out

The overview frames Temporal as a response to Date being a long standing pain point in ECMAScript, and it is introduced as a global object that acts as a top level namespace in the same way Math does. Four principles define the shape of the API. Every Temporal object is immutable, which removes the class of bug where a date value changes under code that holds a reference to it. Date values may be represented in local calendar systems, with a separate document explaining why, but they must be convertible to and from the Proleptic Gregorian Calendar. All time of day values use a standard 24 hour clock, which rules out the 12 hour ambiguity the old API carried. The fourth principle is an omission stated as a rule: leap seconds are not represented at all. Anyone porting code that counts leap seconds has to decide where that logic goes, because the standard will not hold it.

The polyfill in this repository is explicitly not for your project

A polyfill directory exists and is wired into the build, and the README goes out of its way to warn against using it. It is described as a non production polyfill that was built to validate the proposal, and it continues to live in this repository only so that tests can run and so the documentation playground has something to execute. The instruction is blunt: do not use this polyfill in your own projects, and use one from the table instead. That table lists three community projects with their maturity stated: the js-temporal polyfill is at an alpha release, the FullCalendar one is at a stable release, and temporal-polyfill-lite is at a release candidate. Authors working on a polyfill are asked to file an issue or a pull request so theirs can be added to the list, which means the table is expected to change as more options appear.

The docs playground loads that same polyfill into your browser

There is one interactive feature and it depends on the throwaway polyfill. When you open the reference documentation, the non production polyfill is loaded automatically in the browser, so you can open the developer tools console and try Temporal expressions against the real documentation. That is the whole purpose of keeping the polyfill alive in the repository, and it explains why the playground is a documentation feature rather than a testing surface. It also means the examples in the documentation are validated against that implementation, not against a shipping engine, so a reader checking behaviour rather than syntax may see differences from what Firefox or Chrome now do. The documentation itself is published in English, with partial Japanese and partial Chinese translations, and a separate cookbook is linked for getting started.

The build is three targets and lint runs before type checking

The manifest is private and its main entry points into the polyfill, which reflects what the repository is for. The full build runs three sub-builds in order: the polyfill, the documentation and the specification. The specification build invokes ecmarkup with linting enabled and strict mode, loading two bibliography packages whose versions are pinned exactly rather than by range, one for ECMA-262 and one for ECMA-402. Linting is run as eslint over js, mjs and declaration files with a cache and a maximum warnings setting of zero, so a warning fails the command, and a postlint hook then runs a TypeScript check of the polyfill's declaration file with strict mode and the ESNext library. The declared engine floor is Node 12.16.0, which is low enough to say the tooling itself was not the constraint. Formatting the spec is a separate emu command, and updating dependencies is a shell script in the repository root.

Four test entry points, one suite per command

Each test script follows the same shape, changing directory into the polyfill, installing its dependencies and running one suite, which keeps the root free of a second dependency tree. The main test command chains the unit tests, a cookbook test and the test262 suite in that order:

cd polyfill && npm install && npm test && npm run test-cookbook && npm run test262

Running any of them alone is normal practice while developing: the test262 entry point runs only the standards conformance suite, the cookbook entry point validates the documentation recipes, and a separate script named after Demitasse runs the polyfill's own tests. There is also a coverage variant of the test262 run, and codecov.yml at the root is where those results go. The rest of the tree matches this split: spec.html and the spec directory hold the specification source, docs holds the documentation site, meetings holds the committee material, and .gitmodules records that some of it is pulled in from elsewhere.

Nine champions are listed, and the licence is undeclared

The champions section names the people who drove the proposal, and there are nine of them: Philipp Dunkel, Maggie Johnson-Pint, Matt Johnson-Pint, Brian Terlson, Shane Carr, Ujjwal Sharma, Philip Chimento, Jason Williams and Justin Grant. The repository metadata reports no licence, marked as NOASSERTION, even though a LICENSE file is present at the root, so the reuse terms for the specification text and the polyfill are not machine readable. The remaining root entries are development tooling: an eslint configuration, prettier ignore rules, an editor config, codecov configuration, a lock file, and a codecov badge workflow under .github. Taken with the status paragraph, the picture is a project in its final phase, where the specification is finished, the implementations have landed, and what remains is archival.

Editorial conclusion

This repository suits someone reading the specification text, the design rationale behind immutability and calendar conversion, or the cookbook, and someone deciding which of the three community polyfills to depend on. It does not suit someone looking for a maintained library, since the announcement is that the repository will be archived after the merge. Before depending on a polyfill, check its listed status, alpha, stable or release candidate, and remember that the polyfill inside this repository exists only to validate the proposal and to power the documentation playground.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. tc39/proposal-temporal on GitHub