{"id":11190,"library":"jstz","title":"JSTZ - Timezone Detection","description":"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.","status":"maintenance","version":"2.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/iansinnott/jstz","tags":["javascript","time","timezone","tz","moment","moment-timezone","date","typescript"],"install":[{"cmd":"npm install jstz","lang":"bash","label":"npm"},{"cmd":"yarn add jstz","lang":"bash","label":"yarn"},{"cmd":"pnpm add jstz","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily offers a default export. While CommonJS `require('jstz')` works, directly accessing a `.default` property is incorrect for CJS.","wrong":"const jstz = require('jstz').default;","symbol":"jstz","correct":"import jstz from 'jstz';"},{"note":"The `determine` method is accessed as a property of the default `jstz` object, not as a named export.","wrong":"import { determine } from 'jstz';","symbol":"determine","correct":"const timezone = jstz.determine();"},{"note":"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.","wrong":"const timezoneName = jstz.determine().toString();","symbol":"TimeZone.name()","correct":"const timezoneName = timezone.name();"}],"quickstart":{"code":"import jstz from 'jstz';\n\nfunction detectAndDisplayTimezone() {\n  try {\n    const timezone = jstz.determine();\n    const name = timezone.name();\n    console.log(`Detected timezone: ${name}`);\n\n    // Example of using the timezone name (e.g., sending to a server)\n    // fetch('/api/user/timezone', {\n    //   method: 'POST',\n    //   headers: { 'Content-Type': 'application/json' },\n    //   body: JSON.stringify({ timezone: name })\n    // });\n\n    document.getElementById('timezone-output').innerText = `Your detected timezone is: ${name}`;\n  } catch (error) {\n    console.error('Failed to detect timezone:', error);\n    document.getElementById('timezone-output').innerText = 'Failed to detect timezone.';\n  }\n}\n\n// Run detection on page load in a browser environment\nif (typeof window !== 'undefined') {\n  window.addEventListener('load', detectAndDisplayTimezone);\n  // For quick testing in a Node-like environment without a DOM\n  if (!document.getElementById('timezone-output')) {\n    console.log('Running jstz.determine() in a non-DOM context...');\n    const timezone = jstz.determine();\n    console.log(`Node-like detected timezone: ${timezone.name()}`);\n  }\n}","lang":"typescript","description":"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."},"warnings":[{"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.","message":"This `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `jstz@2.0.0` or newer to incorporate the Firefox bug fix: `npm install jstz@latest`.","message":"Version 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.","severity":"breaking","affected_versions":"<2.0.0"},{"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.","message":"Integrating `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always import `jstz` as a default export and access `determine()` as a method on the imported object: `import jstz from 'jstz'; jstz.determine();`","message":"While `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"The `jstz` variable or module was not correctly imported or required in the JavaScript file or global scope.","error":"ReferenceError: jstz is not defined"},{"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.","cause":"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.","error":"TypeError: jstz.determine is not a function"},{"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.","cause":"The object returned by `jstz.determine()` is not the expected TimeZone object, or `name()` is incorrectly called on it.","error":"TypeError: timezone.name is not a function"},{"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.","cause":"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.","error":"TZInfo::UnknownTimezone (or similar Rails errors during timezone lookup)"}],"ecosystem":"npm"}