In node.js, we previously relied on external libraries such as moment.js to handle dates. However, as we try to move towards lighter, performant applications, libraries such as moment.js, which are significantly larger in size, may not fit the bill.
date-fns which offers an alternative solution with a set of helper functions for handling date math and time conversions in node.js and the browser. Now, combined with the
date-fns-tz extension for time-zone support, we can easily handle time-zone specific tasks with lower overhead than ever before.
Understanding the Basics
Now, before we step into Doctor Who's Tardis and begin our gallivanting through time, let's first lay out some groundwork.
date-fns-tz is an extension of
Now, the Internationalization API, abbreviated as the
In the context of date and time conversion, the
Intl API provides date-time formatting capabilities, including supporting different calendar types, numbering systems, time-zones, and more.
Getting Started with date-fns-tz
To make use of
date-fns-tz, you'll first have to install it alongside
date-fns which is a peer dependency. You can add them both to your project with the following commands:
Once installation is complete, you can import the necessary functions from 'date-fns-tz' as per requirement. This library supports both CommonJS and ESM imports.
Let’s first understand what
date-fns-tz allows us to do. With it, we are able to:
- Format dates in any time zone.
- Define a date-time representing local time in a given time zone from the UTC date.
- Convert a known local time in a different time zone to its equivalent UTC time.
A memorable Halloween Party (across Time-Zones)
In order to make our journey more fun and relatable, let's consider a fictional scenario for our examples. In the spirit of Halloween (and since our specific date for examples is 2023 October 20th), let's say you, as the head of global operations at a multinational corporation, are organizing a virtual Halloween party across different spare time-zones simultaneously (a daunting task even without the time-zone issue!).
Now, as part of this party, you want to schedule a global announcement to kick things off. Since all the employees around the world are supposed to join in at the same time, you need to inform them about when the kick-off will happen in their own local time zones.
Formatting Dates in a Timezone
Our first task is to format the date of the party in a specific time zone.
date-fns-tz provides us with a function called
formatInTimeZone for this.
Here, we're organizing a party that starts at 10 PM UTC time on the 20th of October 2023. Using the
formatInTimeZone function, we are able to inform our team-mate in New York that the kick-off will be at 6 PM local time (because New York follows the UTC-4:00 offset).
This way, we can clearly communicate to each teammate around the world when the party will start in their own local time, eliminating any time related confusion!
formatInTimeZone takes a
Date instance, along with the IANA time zone name, and the format in which we want the date-time. This function ensures that we get the date-time in the target time zone.
Converting Local Time to UTC
Now, as we continue with our party planning, we encounter a small hitch. Our party decoration specialist requires time to set up before the party starts. But, he is based out of Tokyo, Japan.
If he tells you that he needs 3 hours for decoration and will finish his setup by 7 PM Tokyo time, then you need to understand what time it will be in UTC to correctly schedule the party starting time.
In such cases,
date-fns-tz provides us a function called
Here, we've used this function to convert the local time in Tokyo to the equivalent UTC time. Now we can plan our kick-off time accordingly and allow for proper setup.
Mvc-ing from UTC to Local Time
Now that we know when the setup will be complete, we need to inform another teammate, let's say in Sydney, Australia, when he should start the music (as we all know, no party starts without music!).
The key here is that because he's in a different time-zone, we have to convert the UTC kick-off time to Sydney time. Fortunately,
date-fns-tz has a function
utcToZonedTime to help us:
So, just by calling this function with the UTC time and the desired time-zone (in this case, 'Australia/Sydney'), we can tell our DJ exactly when to start the music according to his local time in Sydney. This prevents any confusion about the start time of the party (and ensures our beats are not late!).
date-fns-tz library provides more functions in addition to the ones outlined above. Functions like
getTimezoneOffset to calculate the difference in milliseconds between two timezones, or
toDate which can be used to parse a
Date from a string containing a date and time in any time zone.
In the process of orchestrating our fictional multinational Halloween party, we've only begun to scratch the surface of what we can do with
date-fns-tz. Hopefully, this has shown you that working across time-zones doesn't have to be a frightening experience - even around Halloween!
Interested in LogSnag?