Atemporal

Appearance

Temporal Detection ​

Atemporal automatically detects whether the native Temporal API is available in the current environment. This ensures you always get the best performance without changing your code.

How It Works ​

  • Native Temporal Available: Uses the runtime's native implementation.
  • Native Temporal Not Available: Falls back to @js-temporal/polyfill automatically.

The detection runs once and is cached for the lifetime of your application. It searches for Temporal in globalThis, window, global, and self in that order.

Native availability is a runtime capability, not a version promise in this guide. Check it with atemporal.getTemporalInfo() in the environment you deploy. CI validates the native path on Node 26 and validates the polyfill path across the supported Node matrix.

Checking the Implementation ​

ts
import atemporal from "atemporal";

const info = atemporal.getTemporalInfo();
console.log(info);
// {
//   isNative: false,        // true if native Temporal found
//   environment: 'node',    // 'browser', 'node', or 'unknown'
//   version: 'polyfill'     // 'native' or 'polyfill'
// }

Benefits ​

  • No code changes required: Your existing atemporal code works identically whether native or polyfill
  • Automatic performance: Native Temporal is faster than the polyfill, and you get it for free
  • Stable fallback: Native and polyfill selection happens at runtime. The polyfill remains a direct dependency, so native availability alone does not guarantee that a bundler removes it from an application bundle.
  • Seamless migration: As more browsers adopt Temporal, your app automatically benefits

Runtime Support ​

Temporal implementation status changes independently by runtime and release. Do not branch application behavior on a guessed browser or Node version. Use getTemporalInfo() when diagnostics or observability need to distinguish the native and polyfill paths.

Migration ​

No action is required. The detection system is fully backward compatible. Your code continues to work regardless of which Temporal implementation is active:

ts
// This works identically with both native and polyfill Temporal
const date = atemporal("2023-12-25");
const formatted = date.format("YYYY-MM-DD");

Testing ​

For testing scenarios where you need to simulate native Temporal support:

ts
// Mock the global Temporal object in your test setup
globalThis.Temporal = {
  Now: { zonedDateTimeISO: () => { /* mock */ } },
  ZonedDateTime: { from: () => { /* mock */ } },
  // ... other required methods
};

For More Details ​

See the full Temporal Detection deep dive for information about the detection algorithm internals, caching, cross-platform support, and helper utilities like isBrowserEnvironment() and isNodeEnvironment().