Skip to main content
Deno 2 is finally here 🎉️
Learn more

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