JavaScript Temporal Mistakes
Temporal is a powerful API, but it can be confusing at first.
Here are the 10 most common mistakes and how to avoid them.
1. Missing UTC (Z) for Instant
An Instant must always include UTC.
Wrong
Temporal.Instant.from("2026-05-17T14:30:00"); // Error
Correct
Temporal.Instant.from("2026-05-17T14:30:00Z");
2. Using PlainDateTime with Time Zone
PlainDateTime does not support time zones.
Wrong
Temporal.PlainDateTime.from("2026-05-17T14:30:00Z"); // Error
Correct
Temporal.ZonedDateTime.from("2026-05-17T14:30:00Z[UTC]");
3. Comparing Different Types
Temporal does not allow comparing different types.
Wrong
const d = Temporal.PlainDate.from("2026-05-17");
const dt = Temporal.PlainDateTime.from("2026-05-17T14:30");
d.equals(dt); // Error
Correct
d.equals(dt.toPlainDate());
4. Using < or > for Comparison
Temporal objects cannot be compared with < or >.
Wrong
d1 < d2; // Not reliable
Correct
Temporal.PlainDate.compare(d1, d2);
5. Expecting Mutation
Temporal objects are immutable.
Wrong
const d = Temporal.PlainDate.from("2026-05-17");
d.add({ days: 1 });
console.log(d); // unchanged
Correct
const next = d.add({ days: 1 });
6. Using valueOf()
Temporal objects do not convert to numbers.
Example
const dt = Temporal.PlainDateTime.from("2026-05-17T14:30");
try {
console.log(dt.valueOf());
} catch (err) {
console.log(err);
}
7. Using Instant for Local Time
Instant is always UTC.
Wrong
Temporal.Now.instant(); // not local time
Correct
Temporal.Now.zonedDateTimeISO();
8. Using PlainDate for Time
PlainDate has no time.
Wrong
Temporal.PlainDate.from("2026-05-17T14:30"); // Error
Correct
Temporal.PlainDateTime.from("2026-05-17T14:30");
9. Forgetting Time Zone in ZonedDateTime
ZonedDateTime requires a time zone.
Wrong
Temporal.ZonedDateTime.from("2026-05-17T14:30:00"); // Error
Correct
Temporal.ZonedDateTime.from("2026-05-17T14:30:00+02:00[Europe/Oslo]");
10. Not Choosing the Right Type
Each Temporal type has a specific purpose.
| Type | Use |
|---|---|
Instant |
Exact moment (UTC) |
PlainDate |
Date only |
PlainTime |
Time only |
PlainDateTime |
Date + time |
ZonedDateTime |
Date + time + time zone |
Summary
Use the correct Temporal type
Avoid implicit conversions
Always handle time zones correctly
Use compare() instead of < and >
Remember: Temporal is immutable
