The secrets of Firestore’s FieldValue.serverTimestamp() — REVEALED!

Thanks for reading past the opening graphic. It was terrible. Can we just agree I’m a bad graphic artist? Anyway.

If you’ve written any code that deals with timestamps in Firestore, you’ve almost certainly encountered the notion of “server timestamps” using FieldValue.serverTimestamp() (iOS, Android, JavaScript). And I’m willing to bet you found something to be unintuitive about it at first. But that’s OK, because there’s a lot going on behind the scenes that makes it work (or not work as you’d expect).

Make some time for server timestamps

FieldValue.serverTimestamp() is probably the most common FieldValue that you’ll encounter. There are a few different types of FieldValues, and they all act as tokens when writing Firestore document fields. These tokens don’t have a specific value on the client — they are evaluated on the server, at which point the final value is known.

When you call FieldValue.serverTimestamp(), you’ll get back a FieldValue type object that stands in for the current moment in time, as reckoned by Google. The actual value of this FieldValue token doesn’t actually contain any time data in it. You can’t get time values out of it, and you can’t do time math with it. It’s just a token. When you provide the token as…