JSTZ - Timezone Detection

Common errors

• ReferenceError: jstz is not defined

  cause 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

  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.
  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

  cause 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)

  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.
  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.

Warnings

• gotcha 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.
  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.
• breaking 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.
  Fix: Upgrade to `jstz@2.0.0` or newer to incorporate the Firefox bug fix: `npm install jstz@latest`.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Always import `jstz` as a default export and access `determine()` as a method on the imported object: `import jstz from 'jstz'; jstz.determine();`

Install

• npm install jstz npm
• yarn add jstz yarn
• pnpm add jstz pnpm

Imports

• jstz
  wrong:

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

  correct:

  import jstz from 'jstz';

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

  import { determine } from 'jstz';

  correct:

  const timezone = jstz.determine();

  The `determine` method is accessed as a property of the default `jstz` object, not as a named export.
• TimeZone.name()
  wrong:

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

  correct:

  const timezoneName = timezone.name();

  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.

Quickstart

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()}`);
  }
}