jstz

library2.1.1jsnpmunverified

JSTZ is a JavaScript library designed for client-side timezone detection within a user's browser, returning an IANA zone info key (e.g., 'America/Los_Angeles'). It is currently at version 2.1.1. As an unofficial fork of the original `pellepim/jstimezonedetect` project, its primary differentiator is enabling installation and usage via NPM for module-based environments (like Webpack or Browserify), as the original focused on CDN distribution. While there isn't a strict, frequent release cadence, updates have addressed specific bugs and improved TypeScript definitions. It's often used in conjunction with server-side frameworks or other date-time parsing libraries like Moment Timezone to determine the user's local timezone without requiring user input.

serialization

npm install jstz

github ↗package ↗

INSTALL

IMPORT

SIG · JSTZ

jstz

serializationjavascriptv2.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jstz

✓ import jstz from 'jstz';

✗ const jstz = require('jstz').default;

The library primarily offers a default export. While CommonJS `require('jstz')` works, directly accessing a `.default` property is incorrect for CJS.

determine

✓ const timezone = jstz.determine();

✗ import { determine } from 'jstz';

The `determine` method is accessed as a property of the default `jstz` object, not as a named export.

TimeZone.name()

✓ const timezoneName = timezone.name();

✗ const timezoneName = jstz.determine().toString();

The `determine()` method returns an object with a `name()` method to get the IANA timezone string. Simply calling `toString()` on the returned object might not yield the desired IANA name.

This quickstart demonstrates how to import jstz, detect the user's timezone, and display its IANA name. It includes error handling and notes for both browser and Node-like environments.

import jstz from 'jstz'; function detectAndDisplayTimezone() { try { const timezone = jstz.determine(); const name = timezone.name(); console.log(`Detected timezone: ${name}`); // Example of using the timezone name (e.g., sending to a server) // fetch('/api/user/timezone', { // method: 'POST', // headers: { 'Content-Type': 'application/json' }, // body: JSON.stringify({ timezone: name }) // }); document.getElementById('timezone-output').innerText = `Your detected timezone is: ${name}`; } catch (error) { console.error('Failed to detect timezone:', error); document.getElementById('timezone-output').innerText = 'Failed to detect timezone.'; } } // Run detection on page load in a browser environment if (typeof window !== 'undefined') { window.addEventListener('load', detectAndDisplayTimezone); // For quick testing in a Node-like environment without a DOM if (!document.getElementById('timezone-output')) { console.log('Running jstz.determine() in a non-DOM context...'); const timezone = jstz.determine(); console.log(`Node-like detected timezone: ${timezone.name()}`); } }

Debug

Known issues

gotchaThis `jstz` package is an unofficial fork of `pellepim/jstimezonedetect`. While created to enable NPM usage, it means direct feature parity or sync with the original project is not guaranteed. Users might find different versions or features in the original CDN-distributed library.

fix

Always refer to the official GitHub repository (iansinnott/jstz) for this specific NPM package's documentation and issue tracker. If using via CDN, use the original library.

affects: >=1.0.0

breakingVersion 2.0.0 fixed a specific bug in Firefox. Users relying on or encountering timezone detection issues in Firefox with older `jstz` versions (pre-2.0.0) should upgrade to ensure correct functionality.

fix

Upgrade to `jstz@2.0.0` or newer to incorporate the Firefox bug fix: `npm install jstz@latest`.

affects: <2.0.0

gotchaIntegrating `jstz` with server-side frameworks like Ruby on Rails that use `ActiveSupport::TimeZone` requires careful handling. `jstz` provides IANA timezone identifiers (e.g., 'America/New_York'), which may not directly map to the more human-readable names used by Rails (e.g., 'Eastern Time (US & Canada)'). Further complications arise with `window.Intl` which `jstz` utilizes, as `Intl` might identify timezones not recognized by Rails, necessitating workarounds like temporarily silencing `Intl` during `jstz`'s `determine()` call.

fix

Implement explicit mapping logic between IANA timezones and `ActiveSupport::TimeZone` names. For `Intl` conflicts, consider the provided Rails example in the `jstz` README to temporarily undefine `window.Intl` before calling `jstz.determine()` if needed.

affects: >=1.0.0

gotchaWhile `jstz` ships with TypeScript types, incorrect usage of imports (e.g., trying to named import `determine` instead of accessing it as a property) will lead to runtime errors, despite potentially passing TypeScript checks depending on configuration.

fix

Always import `jstz` as a default export and access `determine()` as a method on the imported object: `import jstz from 'jstz'; jstz.determine();`

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: jstz is not defined

The `jstz` variable or module was not correctly imported or required in the JavaScript file or global scope.

fix

For ESM: `import jstz from 'jstz';`. For CJS: `const jstz = require('jstz');`. Ensure script tags are loaded correctly in HTML for global usage (though module systems are recommended for this package).

TypeError: jstz.determine is not a function

The imported `jstz` object does not have a `determine` method, possibly due to incorrect import syntax or module resolution issues. This can occur if a named import was attempted or if a different library with the same name was accidentally loaded.

fix

Verify that `jstz` is imported as a default export (`import jstz from 'jstz';` or `const jstz = require('jstz');`) and that `determine()` is called on the imported object.

TypeError: timezone.name is not a function

The object returned by `jstz.determine()` is not the expected TimeZone object, or `name()` is incorrectly called on it.

fix

Ensure `const timezone = jstz.determine();` is correctly executed and that `name()` is called as a method: `timezone.name()`. Inspect the `timezone` object to confirm its structure if the error persists.

TZInfo::UnknownTimezone (or similar Rails errors during timezone lookup)

The IANA timezone string returned by `jstz` does not have a direct, exact match within the `ActiveSupport::TimeZone` database or `TZInfo` library used by Rails. This is a common integration challenge.

fix

Implement explicit mapping logic on the server-side to translate `jstz`'s IANA names to `ActiveSupport::TimeZone` names. The `jstz` README provides an example `browser_time_zone` helper method for Rails that attempts this translation and provides a fallback.

Upgrade

Version history

2.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/iansinnott/jstz ↗

packagehttps://www.npmjs.com/package/jstz ↗