temporal-polyfill

temporal-polyfill brings the TC39 Temporal proposal to environments that don’t yet support it natively, giving developers a spec-compliant Temporal global (or side-effect-free ponyfill) years before every target browser and Node.js version ships it built in. It supports all time zones and, through its /full/ entrypoints, an expanded set of calendar systems including Buddhist, Chinese, Hebrew, Islamic, and Japanese calendars, alongside the default ISO 8601 and Gregorian calendars covered by the smaller default build.

What sets it apart from other Temporal polyfills is its size and flexibility: at roughly 19.5 kB minified and gzipped, it is well under half the footprint of @js-temporal/polyfill, and it ships an additional tree-shakeable function API (temporal-polyfill/fns/*) for teams that want to import only the specific date/time operations they use. A companion codemod package can later rewrite function-API call sites back into native Temporal.* method calls once a project’s runtime environments no longer need the polyfill, making adoption a two-way door rather than a permanent dependency.

What You Get

• Global, ponyfill, and shim installation modes for the full Temporal class API
• A side-effect-free, tree-shakeable function API under temporal-polyfill/fns/* for bundle-size-sensitive consumers
• Extended calendar-system coverage (Buddhist, Chinese, Hebrew, Islamic, Japanese, Persian, and more) via /full/ entrypoints
• Prebuilt CDN bundles for both the basic and full calendar builds
• TypeScript type overrides so globalThis.Temporal is correctly typed after a global install
• A companion codemod package that rewrites function-API calls back into native Temporal.* syntax once native support lands

Common Use Cases

• Shipping calendar, scheduling, or booking UI features today while waiting for universal native Temporal support
• Building component libraries (date pickers, schedulers) around the tree-shakeable function API as a deletable peer dependency
• Running Node.js services on older LTS versions (16-20) that predate native Temporal support
• Serving users who need non-Gregorian calendar systems such as Hijri, Hebrew, or Japanese calendars

Under The Hood

Architecture The repository is a pnpm-workspace monorepo with four packages — polyfill (the published library), utils, spec, and codemod. Inside polyfill, a pure calculation engine (src/internal/* — ISO calendar math, field parsing/refinement, rounding, diffing, time zone parsing) is shared by two public surface layers: a class-based API mirroring the spec’s Temporal.* classes (src/classApi/basic and src/classApi/full, using a branding/slots pattern defined in src/apiHelpers/branding.ts and src/internal/slots.ts) and a tree-shakeable function API operating on plain records (src/funcApi/*). The basic and full class-API trees are structurally parallel, differing only in which calendar implementations from src/exoticCalendars/* they wire in, letting bundlers exclude unused calendar code. Because both API layers depend on the same internal slot/branding representation, changing that core module would ripple through the entire public surface.

Tech Stack The codebase is almost entirely TypeScript (94.5%), built with tsc for declarations and Rollup (@rollup/plugin-node-resolve, rollup-plugin-dts, @rollup/plugin-terser) for bundling, with a pluggable minification step supporting either Terser or SWC. Package management uses pnpm workspaces, and Biome (pinned to a specific version to avoid a known regression) replaces ESLint/Prettier for linting and formatting. Hand-written Node build scripts (scripts/bundle.js, scripts/manifest.js, scripts/minify.js) drive the many package.json exports subpaths the library ships.

Code Quality Tests are colocated *.test.ts files run through Vitest, including dedicated coverage suites that verify every function-API type mapping is exercised (fns-api-coverage.test.ts, fns-direct-coverage.test.ts, fns-nondirect-coverage.test.ts, fns-type-coverage.test.ts). Beyond unit tests, the project runs the official test262 spec-conformance suite against both the basic and full builds in CI, maintaining a small, explicitly documented list of intentional deviations. CI matrices across six Node.js versions and multiple minifiers, running lint, build, and the full test suite on every push to main.

API Design The standout design choice is offering two parallel APIs over the same engine: a class-based API matching the official Temporal proposal’s shape one-for-one, for near-zero migration friction, and a tree-shakeable function API for bundle-conscious consumers, with a codemod bridging the two. Naming follows the TC39 Temporal proposal’s own conventions closely, minimizing the learning curve for anyone familiar with the spec or MDN docs. Getting started requires a single import with no configuration for the common case, though pre-6.0 TypeScript users need one extra type-only import — a small, well-documented piece of friction. Documentation is thorough, with every entrypoint demonstrated in the README and a dedicated docs/fns/ tree covering the function API type by type.