minitz

Converting between different timezones in pure JavaScript is tricky. This minimal library tries to solve that problem in the simplest possible way.

Minitz can convert date and time to/from any timezone supported by the system (Node/Deno/Browser). Compatible with both ESM or UMD/CommnJS.

Node.js CI Deno CI npm version NPM Downloads jsdelivr Codacy Badge MIT License

  • Convert Dates between to/from any timezone.
  • MIT licensed, use the library any way you want. For real.
  • Minimal, no dependencies. Relies on JavaScript Intl and current best practises.
  • Works in Node.js >=14.0 (both require and import).
  • Works in Deno >=1.8.
  • Works in browsers as standalone, UMD or ES-module.
  • Includes TypeScript typings.

Documentation

Full documentation available at hexagon.github.io/minitz.

Installation

Node.js

npm install minitz --save

JavaScript

// ESM Import ...
import minitz from "minitz";

// ... or CommonJS Require
const minitz = require("minitz");

TypeScript

Note that only default export is available in Node.js TypeScript, as the commonjs module is used internally.

import minitz from "minitz";

// ...

Deno

JavaScript

import minitz from "https://cdn.jsdelivr.net/gh/hexagon/minitz/src/minitz.js";

// ...

TypeScript

import { minitz } from "https://cdn.jsdelivr.net/gh/hexagon/minitz/src/minitz.js";

// ...

Browser

Manual

  • Download latest zipball
  • Unpack
  • Grab minitz.min.js (UMD and standalone) or minitz.min.mjs (ES-module) from the dist/ folder

CDN

To use as a UMD-module (stand alone, RequireJS etc.)

<script src="https://cdn.jsdelivr.net/npm/minitz/dist/minitz.min.js"></script>

To use as a ES-module

<script type="module">
    import minitz from "https://cdn.jsdelivr.net/npm/minitz/dist/minitz.min.mjs";

    // ... see usage section ...
</script>

Examples

Assuming you have imported minitz as described under 'Installation'.

Convert from a specific timezone to local time

// Convert 2022-09-10 23:08:09 in New York to local time (in this example Europe/Stockholm)
console.log("Local time: ", minitz(2022, 9, 10, 23, 8, 9, "America/New_York").toLocaleString("sv-SE"));
// Local time:  2022-09-11 05:08:09

Convert local time to a specific timezone

//  Convert to local time to time in America/New_York
//  As time in other timezones than local cannot be represented correctly by a date object
//  a generic object is returned
console.log("Time in New York: ", minitz.toTZ(new Date(), "America/New_York"));
// -> Time in New York: 
//  {
//     year: 2022,
//     month: 9,
//     day: 14,
//     hour: 17,
//     minute: 29,
//     second: 42,
//     timezone: 'America/New_York'
//  }

Convert local time to specific timezone, returning faux date object with normal formatting functions available

const timeInNewYork = minitz.toTZ(new Date(), "America/New_York");
console.log("Time in New York printed with system locale: ", minitz.fauxDate(timeInNewYork).toLocaleString("sv-SE"));
// -> Time in New York printed with system locale:  2022-09-14 17:29:42

Contributing

Any contributions are welcome. See Contribution Guide

License

MIT