@vvo/tzdb

What is @vvo/tzdb?

@vvo/tzdb is an npm package that provides a comprehensive database of time zones. It allows developers to easily access and manipulate time zone data, including retrieving time zone names, offsets, and other related information.

What are @vvo/tzdb's main functionalities?

Get all time zones

This feature allows you to retrieve a list of all available time zones. The code sample demonstrates how to use the `getTimeZones` function to get an array of time zone objects.

const { getTimeZones } = require('@vvo/tzdb');
const timeZones = getTimeZones();
console.log(timeZones);

Get time zone by name

This feature allows you to retrieve detailed information about a specific time zone by its name. The code sample shows how to use the `getTimeZone` function to get details for the 'America/New_York' time zone.

const { getTimeZone } = require('@vvo/tzdb');
const timeZone = getTimeZone('America/New_York');
console.log(timeZone);

Get time zone offset

This feature allows you to get the offset of a specific time zone. The code sample demonstrates how to use the `getTimeZoneOffset` function to get the offset for the 'America/New_York' time zone.

const { getTimeZoneOffset } = require('@vvo/tzdb');
const offset = getTimeZoneOffset('America/New_York');
console.log(offset);

Other packages similar to @vvo/tzdb

moment-timezone

Moment-timezone is a popular package that extends the Moment.js library to handle time zones. It provides similar functionalities to @vvo/tzdb, such as retrieving time zone data and converting between time zones. However, it is built on top of Moment.js, which can be heavier and more complex compared to @vvo/tzdb.

luxon

Luxon is a modern JavaScript library for working with dates and times. It includes built-in support for time zones and offers a more modern API compared to Moment.js. Luxon provides similar functionalities to @vvo/tzdb but also includes additional features for date and time manipulation.

date-fns-tz

Date-fns-tz is an extension of the date-fns library that adds support for time zones. It provides functions to convert dates between time zones and to get time zone offsets. Date-fns-tz offers a lightweight and functional approach to handling time zones, similar to @vvo/tzdb.

README

tzdb

This is a list and npm package of:

• "simplified" IANA time zones with their alternative names like Pacific Time instead of America/Los_Angeles, along with major cities for each time zone.
• all existing raw IANA time zones names

The data and npm packages are automatically updated whenever there are changes to https://www.geonames.org/ which is generated from IANA databases.

This is useful whenever you want to build a time zone select menu in your application.

Available data

simplified-time-zones.json

This is most probably what you're looking for if you're trying to build a time zones selector in your application.

Example data:

[
  // ...
  {
    name: "America/Anchorage",
    alternativeName: "Alaska Time",
    mainCities: ["Anchorage", "Juneau"],
    formatted: "-09:00 Alaska Time - Anchorage, Juneau",
    group: [
      "America/Anchorage",
      "America/Juneau",
      "America/Metlakatla",
      "America/Nome",
      "America/Sitka",
      "America/Yakutat",
    ],
  },
  {
    name: "Pacific/Gambier",
    alternativeName: "Gambier Time",
    mainCities: ["Gambier"],
    formatted: "-09:00 Gambier Time - Gambier",
    group: ["Pacific/Gambier"],
  },
  {
    name: "America/Los_Angeles",
    alternativeName: "Pacific Time",
    mainCities: ["Los Angeles", "San Diego"],
    formatted: "-08:00 Pacific Time - Los Angeles, San Diego",
    group: ["America/Los_Angeles"],
  },
  // ...
];

As you can see, we provide the time zone name and a pre-formatted version using more common offset names.

Notes:

• Grouping: when two different time zones names are in the same country, same offset and dst rules then we merge them and select the time zone name from the biggest city
• We provide two cities when grouping happens, ranked by population
• We provide offset names ("Pacific Time") without dst and remove "Standard" and "Daylight"
• The offsets (-08:00) are always the "raw offsets", the ones when there's no summer time or daylight saving time in place for the time zone. We decided not to include the current date offset. Because then you would have to upgrade this library in your application as soon as it would be updated with the new "current offset". But we provide a function, formatTimeZone to compute the same formatted structure, with the current date offset, at runtime instead of buildtime
• This can be used to build a good enough (Google calendar like) select box of time zones, but it's your responsibility to handle dst and real offsets using luxon for example

time-zones-names.json

This is the raw list of all IANA time zones ranked by alphabetical order.

Example data:

[
  // ...
  "America/La_Paz",
  "America/Lima",
  "America/Los_Angeles",
  "America/Lower_Princes",
  "America/Maceio",
  "America/Managua",
  "America/Manaus",
  "America/Marigot",
  "America/Martinique",
  // ...
];

NPM package

Installation:

npm add @vvo/tzdb

Usage:

import { simplifiedTimeZones, timeZonesNames, formatTimeZone } from "@vvo/tzdb";

API

simplifiedTimeZones

timeZonesNames

formatTimeZone(simplifiedTimeZone, { useCurrentOffset = false })

You can use this function when you want to get a formatted time zone but with the current date offset. This is useful if you always want to show the real, current time zone offset.

Example usage:

import { simplifiedTimeZones, formatTimeZone } from "@vvo/tzdb";

console.log(
  formatTimeZone(simplifiedTimeZones[10], { useCurrentOffset: true }),
);
// output when in DST:
// -07:00 Pacific Time - Los Angeles, San Diego

This function uses luxon internally, so it would be better for your build size to also use luxon in your application whenever you need to manipulate dates.

PS: If you'd like to contribute to this library, we could make it so that formatTimeZone is not luxon dependant, for example taking the code here: https://github.com/mobz/get-timezone-offset. Open an issue!

[BETA] Algolia

You can store cities information on a search engine like Algolia. There's a yarn generate command you can use if you clone this repository to create your own Algolia index. The expected environment variables are:

ALGOLIA_APPLICATION_ID=... ALGOLIA_ADMIN_API_KEY=... ALGOLIA_INDEX_NAME=... yarn build

Here's a demo of the index: