Using Hermes? Prefer native Intl
We recommend the Rust-backed Hermes Intl SDK over TypeScript polyfills for Hermes apps. It installs twelve Intl APIs before your application JavaScript runs, with locale data compiled into the SDK.
Get started with native Intl. Native integration requires rebuilding your app. Use TypeScript polyfills when you cannot add native code.
A polyfill/ponyfill for Intl.supportedValuesOf.
Installation#
npm i @formatjs/intl-supportedvaluesof
Requirements#
Usage#
Timezone enumeration uses pinned IANA/CLDR primary IDs, including country-specific
IDs such as Africa/Accra. It omits aliases such as America/Yellowknife.
The installed DateTimeFormat must accept each returned ID; its resolved spelling
may differ on older hosts.
Simple#
import '@formatjs/intl-supportedvaluesof/polyfill.js'
Dynamic import + capability detection#
async function polyfill() {
// This platform already supports Intl.supportedValuesOf
if (shouldPolyfill()) {
await import('@formatjs/intl-supportedvaluesof/polyfill.js')
}
// Alternatively, force the polyfill regardless of support
await import('@formatjs/intl-supportedvaluesof/polyfill-force.js')
}
Native Hermes SDK#
The shared Hermes SDK also provides
Intl.supportedValuesOf. Build and extract it on Linux, then link
@formatjs_intl_getcanonicallocales_hermes//:supported_values in the consumer.
It contains a prebuilt Rust archive; consumers need Hermes and a C++ toolchain,
not a Rust compiler. See the SDK guide for desktop
and Android packages and installation of all twelve APIs.
Install trusted Intl.DateTimeFormat, Intl.NumberFormat and Intl.Collator
implementations first. Rust filters CLDR/IANA candidates against those
formatters' actual capabilities. Missing formatters produce empty categories;
the installer does not supply the formatters themselves.
#include <formatjs/hermes/supported_values.h>
formatjs::installSupportedValuesOf(*runtime);
For bytecode-only extension startup, compile the SDK's js/extensions.js with
the matching hermesc, evaluate it to obtain extensions, then call:
formatjs::installSupportedValuesOf(*runtime, extensions);
For Hermes core/contrib registration, add js/31-IntlSupportedValuesOf.js to
the extension source list and call the same two-argument installer from its
C++ dispatcher. See the SDK instructions
and standalone consumer.
Tests#
The Bazel :test262 target runs the upstream suite against a reviewed failure baseline. A green baseline check does not mean every test passed. See the conformance report; run bazel test //packages/intl-supportedvaluesof:test262-strict to require zero failures.
//packages/intl-supportedvaluesof:rust_conformance_test compares every Rust
output list with TypeScript using real host formatter observations.
//native/hermes/tests:supported_values_conformance_test repeats the comparison
inside Hermes with real TS formatters and checks coercion, exception identity,
function descriptors and fresh result arrays. Linux BuildBuddy builds/tests
the SDK and cross-compiles the standalone consumer; macOS only runs its
downloaded executable and bytecode.
Key coercion#
Intl.supportedValuesOf converts its key to a string before validating the
category. String wrapper objects are accepted; Symbols throw TypeError.
Intl.supportedValuesOf is callable but cannot be used as a constructor.
Time-zone candidates include the pinned IANA etcetera Zone records and UTC,
in addition to continental transition zones. Runtime filtering retains primary
identifiers and omits aliases such as Etc/UTC.
Collation enumeration probes CLDR-derived candidate locales for each type,
including locale-specific collations such as German phonebk and Spanish trad.
Only collations accepted by the installed Collator are returned.
Measured performance#
TypeScript and native JavaScript#
Measured 2026-10-31 on Apple M4 Max, macOS arm64, Node 24.14.0 / ICU 78.2; source 56d15e997. Median of seven warmed rounds.
| Operation | TS ops/s | TS full helpers ops/s | Native JS ops/s |
|---|---|---|---|
| calendar | 29,875 | 45,964 | 319,540† |
| timeZone | 1,193 | 1,702 | 16,757 |
| unit | 10,122 | 39,207 | 519,946 |
TS uses host Intl helpers; TS full helpers installs all FormatJS Intl APIs.
Module loading and data registration are excluded. Construction rows include
resolvedOptions(). These are desktop microbenchmarks; native locale data may
differ. † marks noisy rows (round max/min > 1.5). See workloads, commands, and raw results.
Rust core#
| Rust core operation | µs/call | Rust core ops/s |
|---|---|---|
| calendar | 878.891 | 1,138 |
| timeZone | 20653.490 | 48 |
| unit | 60.491 | 16,531 |
Same machine and source revision, optimized Rust build, seven warmed rounds. Rust core timings exclude Hermes/JSI and JS boundary work; inputs are prepared Rust strings/UTF-16. Data and API-boundary differences prevent direct speedup claims against TS/native JS. † marks round max/min > 1.5. Workload details and raw results.