Temporal is a powerful API, but it can be confusing at first.
- Remember to use the correct Temporal type
- Avoid implicit conversions
- Always handle time zones correctly
- Use compare() instead of < and >
- Remember that Temporal Objects are immutable
Here are some common mistakes and how to avoid them.
Missing UTC (Z) for Instant
An Instant must always include UTC.
Wrong
js
const instant = Temporal.Instant.from("2026-05-17T14:30:00");
Correct
js
const instant = Temporal.Instant.from("2026-05-17T14:30:00Z");
Using PlainDateTime with Time Zone
PlainDateTime does not support time zones.
Wrong
js
const date = Temporal.PlainDateTime.from("2026-05-17T14:30:00Z");
Correct
js
const date = Temporal.ZonedDateTime.from("2026-05-17T14:30:00");
Comparing Different Types
Temporals can go wrong when comparing different types.
Wrong
js
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.Instant.from("2026-05-17T14:30Z");
Temporal.PlainDate.compare(d1, d2);
Correct
js
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.PlainDateTime.from("2026-05-17T14:30");
Temporal.PlainDate.compare(d1, d2);
Using equals() with Different Types
Temporals can go wrong when comparing different types.
Wrong
js
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.Instant.from("2026-05-17T14:30Z");
d1.equals(d2);
Correct
js
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.PlainDateTime.from("2026-05-17T14:30");
d1.equals(d2.toPlainDate());
Using ==, < or > for Comparison
Temporal objects cannot be compared with ==, ===, < or >.
Wrong
js
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.PlainDate.from("2026-05-17");
d1 === d2; // False
d1 == d2; // False
d1 < d2; // TypeError
d1 > d2; // TypeError
Correct
js
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.PlainDate.from("2026-05-17");
Temporal.PlainDate.compare(d1, d2);
Expecting Mutation
Temporal objects are immutable.
Wrong
js
const date = Temporal.PlainDate.from("2026-05-17");
date.add({ months: 1 });
Correct
js
const date = Temporal.PlainDate.from("2026-05-17");
const next = d.add({ months: 1 });
Using valueOf()
Temporal objects do not convert to numbers.
Example
js
const date = Temporal.PlainDate.from("2026-05-17");
try {
text = date.valueOf();
} catch (err) {
text = err.name;
}
Using Instant for Local Time
Instant is always UTC (not local time).
Wrong
js
Temporal.Now.instant(); // not local time
Correct
Use Temporal. Now.zonedDateTimeISO() to get local time:
js
Temporal.Now.zonedDateTimeISO();
Using PlainDate for Time
PlainDate has no time.
Wrong
js
Temporal.PlainDate.from("2026-05-17T14:30");
Correct
js
Temporal.PlainDateTime.from("2026-05-17T14:30");
Forgetting Time Zone in ZonedDateTime
ZonedDateTime requires a time zone.
Wrong
js
Temporal.ZonedDateTime.from("2026-05-17T14:30:00");
Correct
js
Temporal.ZonedDateTime.from("2026-05-17T14:30:00+02:00[Europe/Oslo]");
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 only |
| ZonedDateTime | Date + time + time zone |
| Duration | Length of time only |