date-fns Time Zone Support

Common errors

• TypeError: Cannot read properties of undefined (reading 'formatToParts')

  cause The `Intl.DateTimeFormat` API is not available or incomplete in the current JavaScript environment.
  fix Ensure the runtime environment supports `Intl.DateTimeFormat` or include a polyfill (e.g., `@formatjs/intl-datetimeformat`).

• Error: date-fns-tz is an ESM-only package and cannot be used in CommonJS. (Or similar import/require errors)

  cause Incorrect import statement or module resolution configuration for a hybrid ESM/CJS package.
  fix While `date-fns-tz` supports both CJS and ESM via `exports` field, ensure your `package.json` `type` field is correctly set to `module` for ESM projects or `commonjs` for CJS projects. Use `import { func } from 'date-fns-tz'` for ESM and `const { func } = require('date-fns-tz')` for CJS.

• TypeError: (0 , date_fns_tz__WEBPACK_IMPORTED_MODULE_3__.utcToZonedTime) is not a function

  cause Attempting to use the old `utcToZonedTime` or `zonedTimeToUtc` function name after upgrading to v3.0.0+.
  fix Update the function call to the new names: `toZonedTime` and `fromZonedTime`.

• TypeError: (0 , date_fns_tz__WEBPACK_IMPORTED_MODULE_3__.default) is not a function (or similar error indicating default import issue)

  cause Attempting to use a default import for a function that is exported as a named export.
  fix Change the import statement to use named exports: `import { functionName } from 'date-fns-tz';` (for ESM) or `const { functionName } = require('date-fns-tz');` (for CommonJS).

Warnings

• breaking date-fns-tz v3.0.0 removed support for date-fns v2. Ensure your project uses date-fns v3 or v4.
  Fix: Upgrade date-fns to a compatible version (`^3.0.0 || ^4.0.0`) or downgrade date-fns-tz to a v2-compatible version (e.g., v2.x for date-fns v2).
• breaking Functions `utcToZonedTime` and `zonedTimeToUtc` were renamed to `toZonedTime` and `fromZonedTime` respectively in v3.0.0.
  Fix: Globally search and replace `utcToZonedTime` with `toZonedTime` and `zonedTimeToUtc` with `fromZonedTime` in your codebase.
• breaking All functions are now exported using named exports (ESM style) since v3.0.0, even for CommonJS. Direct default imports or destructuring from `require('date-fns-tz')` for CommonJS will fail if not using named exports.
  Fix: Update all imports to use named exports: `import { functionName } from 'date-fns-tz'` for ESM or `const { functionName } = require('date-fns-tz')` for CommonJS. Do not use `import functionName from 'date-fns-tz'` or `const functionName = require('date-fns-tz')`.
• gotcha This library relies on the browser's native `Intl` API for time zone resolution. Older browsers or environments (like certain Node.js versions or custom builds) might require a polyfill for `Intl.DateTimeFormat`.
  Fix: For environments without full `Intl` API support, include a polyfill like `@formatjs/intl-datetimeformat`. If IANA time zone names are not available, only offsets like `'+0200'` or `'-04:00'` can be used.
• gotcha The `date-fns` dependency is a peer dependency. You must install `date-fns` separately and ensure its version is compatible with `date-fns-tz`.
  Fix: Install `date-fns` explicitly: `npm install date-fns`. Check `package.json` for compatible versions if you encounter issues.

Install

• npm install date-fns-tz npm
• yarn add date-fns-tz yarn
• pnpm add date-fns-tz pnpm

Imports

• formatInTimeZone
  wrong:

  const { formatInTimeZone } = require('date-fns-tz')

  correct:

  import { formatInTimeZone } from 'date-fns-tz'

  Since v3.0.0, all functions are named exports. CommonJS users should also use named exports. This is the primary function for displaying dates in a specific timezone.
• toZonedTime
  wrong:

  import { utcToZonedTime } from 'date-fns-tz'

  correct:

  import { toZonedTime } from 'date-fns-tz'

  Renamed from `utcToZonedTime` to `toZonedTime` in v3.0.0 for clarity. Converts a Date object (assumed UTC) or string to a Date object representing the time in the specified time zone.
• fromZonedTime
  wrong:

  import { zonedTimeToUtc } from 'date-fns-tz'

  correct:

  import { fromZonedTime } from 'date-fns-tz'

  Renamed from `zonedTimeToUtc` to `fromZonedTime` in v3.0.0. Converts a Date object or string (assumed to be in the specified time zone) to a Date object representing the equivalent UTC time.
• format

  import { format } from 'date-fns-tz'

  This is an extended version of `date-fns/format` that supports time zone tokens (e.g., `z`, `zzzz`). Do not confuse with `date-fns`'s own `format` function if time zone formatting is needed.

Quickstart

Demonstrates parsing a UTC date string, then formatting it directly in a specific IANA time zone using `formatInTimeZone`, and converting it to a 'local' date in that time zone using `toZonedTime` for further processing with `date-fns`.

import { formatInTimeZone, toZonedTime } from 'date-fns-tz';
import { parseISO, format } from 'date-fns';

const dateString = '2024-04-21T18:30:00Z'; // UTC date string
const timeZone = 'America/Los_Angeles';

// Parse the ISO string to a Date object (which will be in UTC internally)
const utcDate = parseISO(dateString);

// Format the UTC date directly into the target timezone
const formattedTimeInLA = formatInTimeZone(utcDate, timeZone, 'yyyy-MM-dd HH:mm:ss zzz');

// Convert the UTC date to a Zoned Date object (representing local time in LA)
const zonedDateInLA = toZonedTime(utcDate, timeZone);

// Format the zoned date using date-fns's format (since it's now a 'local' date in LA)
const formattedZonedDate = format(zonedDateInLA, 'yyyy-MM-dd HH:mm:ss');

console.log(`Original UTC: ${dateString}`);
console.log(`Formatted in ${timeZone} (with timezone token): ${formattedTimeInLA}`);
console.log(`Zoned Date in ${timeZone}: ${zonedDateInLA.toISOString()}`); // Shows as if local time, but internally still UTC
console.log(`Formatted Zoned Date in ${timeZone}: ${formattedZonedDate}`);