Guides
Temporal & Safari
Why the engine speaks Temporal, calendar challenges, automatic Date fallback and Safari polyfill.
Why does a calendar need Temporal?
A calendar deals with two fundamentally different kinds of questions:
- Known instant: “This meeting starts at
08:00Z. What time should Alice see in Tokyo?”DateandIntlcan answer that. - Calendar rule: “This meeting starts every Monday at 09:00 in Berlin. What are its future UTC instants?” The answer depends on Berlin’s clock rules for each individual date.
When native Temporal or the polyfill is available, the engine uses separate types for zoned moments, dates without times, and calendar durations to keep DST transitions, all-day events, and recurring series correct.
Temporal support & Safari
Native Temporal support depends on the browser or runtime version. Check globalThis.Temporal or callisTemporalAvailable() in your application.
Safari and older browsers may not provide native Temporal; check at runtime instead of relying on the browser name. To ensure exact DST and recurrence calculations when it is absent, install temporal-polyfill:
npm install temporal-polyfill
Avoiding polyfill downloads where Temporal is native
If you use a static import 'temporal-polyfill/global', bundlers (Vite, Webpack, esbuild) include the polyfill in the main bundle, so browsers with native Temporal download code they do not need. Load the polyfill only when the runtime check says it is absent.
To avoid this, use a conditional dynamic import before mounting your application:
// main.tsx (or application entry point) import { createRoot } from 'react-dom/client' import { App } from './App' // Only downloads the polyfill chunk in browsers without native Temporal (e.g. Safari). // Browsers with native Temporal skip the polyfill chunk. if (!('Temporal' in globalThis)) { await import('temporal-polyfill/global') } const container = document.getElementById('root') if (container) { createRoot(container).render(<App />) }
In browsers with native Temporal, 'Temporal' in globalThis evaluates to true, so the chunk is never requested (0 KB downloaded). In Safari, the chunk is loaded before the application renders. Use the same runtime check for any browser without native Temporal.
Alternatively, if bundle splitting is not a concern, a static import in your entry module also works:
// Application entry module (e.g. index.ts or main.tsx) // Simpler, but bundles the polyfill even for browsers with native Temporal. import 'temporal-polyfill/global'
Server rendering
On server runtimes without native Temporal, import temporal-polyfill/global at startup (e.g. in instrumentation.ts in Next.js, or your server entry) before any calendar calls — Server rendering has the full details.
Why Date is not enough: real-world calendar problems
1. A weekly meeting stays at 09:00 when clocks change
Suppose an organizer creates a recurring Monday meeting at 09:00 Berlin time. Berlin moves its clocks forward by one hour on March 29, 2026. The same 09:00 meeting has a different UTC time the following Monday:
- March 23: 09:00 Berlin =
08:00Z(UTC+1) - March 30: 09:00 Berlin =
07:00Z(UTC+2)
// A weekly Monday meeting at 09:00 in Berlin: // Berlin moves clocks forward on March 29, 2026 (DST transition). // March 23: 09:00 Berlin = 08:00Z (UTC+1) // March 30: 09:00 Berlin = 07:00Z (UTC+2) const weeklyMeeting = { id: 'team-sync', start: '2026-03-23T09:00:00', timeZone: 'Europe/Berlin', recurrence: { rule: 'FREQ=WEEKLY;BYDAY=MO' }, }
Why a simple Date calculation fails: A Date stores a fixed UTC instant, not the instruction “09:00 in Berlin every Monday”. Adding 7 × 24 hours to March 23 at 08:00Z produces March 30 at 08:00Z = 10:00 Berlin. Intl can display that instant, but formatting cannot turn an incorrect 10:00 instant into the intended 09:00 meeting.
2. “One calendar day” is not always 24 hours
A room reservation runs from 09:00 Saturday to 09:00 Sunday in New York. The booking means “until the same local clock time tomorrow”, expressed as P1D.
New York moves its clocks forward overnight on March 8, 2026:
- One calendar day (
P1D): ends at March 8, 09:00 (23 real elapsed hours). - Exactly 24 hours (
PT24H): ends at March 8, 10:00 (24 real elapsed hours).
// In New York, clocks move forward overnight on March 8, 2026. // 'P1D' (calendar day) keeps wall time: ends at March 8, 09:00 (23 elapsed hours). // 'PT24H' (exact elapsed hours) ends at March 8, 10:00 (24 elapsed hours). const roomBooking = { id: 'room-reservation', start: '2026-03-07T09:00:00', timeZone: 'America/New_York', duration: 'P1D', }
start.getTime() + 86_400_000 always adds 24 elapsed hours, so it ends the booking at 10:00. Temporal maintains the distinction between a calendar day and elapsed hours.
3. A clock reading can be missing or happen twice
When clocks spring forward (e.g. 01:59 → 03:00), 02:30 never occurs on the wall clock. When clocks fall back in autumn (e.g. 01:59 → 01:00), 01:30 occurs twice.
Chronous relies on Temporal’s disambiguation policies (compatible, earlier, later, reject) to resolve ambiguous wall-clock entries deterministically rather than relying on host-device assumptions.
4. A holiday on January 1 is a date, not midnight UTC
An all-day event or holiday is a date, not an instant at midnight UTC. In traditional JavaScript, new Date('2026-01-01') parses as UTC midnight, which displays as December 31 at 16:00 in Los Angeles. Chronous treats all-day events as plain dates (YYYY-MM-DD) so they never slip across day boundaries.
When is Date + Intl enough?
If your server sends ordinary events with fixed UTC starts and ends, Chronous converts and places them in range.timeZone accurately through its fallback, without requiring the polyfill:
import { buildCalendar } from '@midstem/chronous-react' const range = { view: 'day', currentDate: '2026-03-18', timeZone: 'Europe/Berlin', } as const // When the server sends fixed UTC instants, Date + Intl is sufficient to display them const events = [ { id: 'server-meeting', start: '2026-03-18T08:00:00Z', end: '2026-03-18T09:00:00Z', }, ] buildCalendar(range, events) // Displays 09:00–10:00 in Berlin
The same applies if your server pre-expands recurring rules and delivers each occurrence as a distinct fixed UTC event.
Automatic Date + Intl fallback
Without native Temporal or a global polyfill, Chronous automatically switches to an internal Date and Intl fallback and logs a console warning. Missing Temporal alone does not throw, but invalid ranges can still raise InvalidRangeError, and fallback limits may omit unsupported events with a warning. Input and output types remain the same.
import { buildCalendar, isTemporalAvailable } from '@midstem/chronous-react' // Reports whether native Temporal or global polyfill is present console.log(isTemporalAvailable()) // true or false // If Temporal is absent, Chronous automatically falls back to an internal // Date + Intl engine and logs a console warning — no crash, identical output types. const calendar = buildCalendar(range, events)
- What works in the fallback: All five views, fixed-offset events, all-day dates, and clock-only timed durations such as
PT4H. Floating timed events are omitted; timed durations with calendar units such asP1Duse approximate elapsed lengths and can differ at DST transitions. Recurring series expand approximately within the visible range. - Limits: The fallback lets supported events render when the polyfill is omitted, but it is not a full scheduling engine. Install the polyfill for exact DST transitions, recurrence rules, calendar-day duration arithmetic, and wall-clock disambiguation.
- Runtime check:
isTemporalAvailable()reports whetherglobalThis.Temporalis present.