@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 good current 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"
• 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

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 timeZones from "@vvo/tzdb/time-zones-names.json";
import simplifiedTimeZones from "@vvo/tzdb/simplified-time-zones.json";

[BETA] Algolia

You can store cities information on a search engine like Algolia. There's a yarn build 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: