JavaScript Temporal Mistakes
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
const instant = Temporal.Instant.from("2026-05-17T14:30:00");
Try it Yourself »
Correct
const instant = Temporal.Instant.from("2026-05-17T14:30:00Z");
Try it Yourself »
Using PlainDateTime with Time Zone
PlainDateTime does not support time zones.
Wrong
const date = Temporal.PlainDateTime.from("2026-05-17T14:30:00Z");
Try it Yourself »
Correct
const date = Temporal.ZonedDateTime.from("2026-05-17T14:30:00");
Try it Yourself »
Comparing Different Types
Temporals can go wrong when comparing different types.
Wrong
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.Instant.from("2026-05-17T14:30Z");
Temporal.PlainDate.compare(d1, d2);
Try it Yourself »
Correct
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.PlainDateTime.from("2026-05-17T14:30");
Temporal.PlainDate.compare(d1, d2);
Try it Yourself »
Using equals() with Different Types
Temporals can go wrong when comparing different types.
Wrong
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.Instant.from("2026-05-17T14:30Z");
d1.equals(d2);
Try it Yourself »
Correct
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.PlainDateTime.from("2026-05-17T14:30");
d1.equals(d2.toPlainDate());
Try it Yourself »
Using ==, < or > for Comparison
Temporal objects cannot be compared with ==, ===, < or >.
Wrong
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
Try it Yourself »
Correct
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.PlainDate.from("2026-05-17");
Temporal.PlainDate.compare(d1, d2);
Try it Yourself »
Expecting Mutation
Temporal objects are immutable.
Wrong
const date = Temporal.PlainDate.from("2026-05-17");
date.add({ months: 1 });
Try it Yourself »
Correct
const date = Temporal.PlainDate.from("2026-05-17");
const next = d.add({ months: 1 });
Try it Yourself »
Using valueOf()
Temporal objects do not convert to numbers.
Example
const date = Temporal.PlainDate.from("2026-05-17");
try {
text = date.valueOf();
} catch (err) {
text = err.name;
}
Try it Yourself »
Using Instant for Local Time
Instant is always UTC (not local time).
Wrong
Temporal.Now.instant(); // not local time
Try it Yourself »
Correct
Use Temporal.Now.zonedDateTimeISO() to get local time:
Temporal.Now.zonedDateTimeISO();
Try it Yourself »
Using PlainDate for Time
PlainDate has no time.
Wrong
Temporal.PlainDate.from("2026-05-17T14:30");
Try it Yourself »
Correct
Temporal.PlainDateTime.from("2026-05-17T14:30");
Try it Yourself »
Forgetting Time Zone in ZonedDateTime
ZonedDateTime requires a time zone.
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 |
