Registry / serialization / date-fns-tz

date-fns-tz

JSON →
library3.2.0jsnpmunverified

date-fns-tz provides robust time zone functionality for date-fns v3 and v4, leveraging the browser's native `Intl` API to avoid bundling large time zone data files. The current stable version is 3.2.0. This library is designed to work seamlessly with `date-fns`'s immutable `Date` object approach, offering functions like `formatInTimeZone` to format dates in a specified IANA time zone, and conversion utilities such as `toZonedTime` and `fromZonedTime` for shifting dates between UTC and specific time zones. It is a peer dependency of `date-fns`, requiring a compatible version (`^3.0.0 || ^4.0.0`). Its release cadence is tied to major `date-fns` versions, with minor updates for features and bug fixes. Key differentiators include its lightweight nature due to `Intl` API reliance and its adherence to the `date-fns` philosophy of pure functions and native Date objects.

npm install date-fns-tz
INSTALL
IMPORT
SIG · DATE-FNS-TZ
D
date-fns-tz
serializationjavascriptv3.2.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

formatInTimeZone
import { formatInTimeZone } from 'date-fns-tz'
const { formatInTimeZone } = require('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
import { toZonedTime } from 'date-fns-tz'
import { utcToZonedTime } 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
import { fromZonedTime } from 'date-fns-tz'
import { zonedTimeToUtc } 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.

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}`);
Debug
Known issues
breakingdate-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).
affects: >=3.0.0
breakingFunctions `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.
affects: >=3.0.0
breakingAll 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')`.
affects: >=3.0.0
gotchaThis 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.
affects: >=0.1.0
gotchaThe `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.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'formatToParts')
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)
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
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)
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).
Upgrade
Version history
3.2.0latest on npm
Audit
Dependencies
date-fnsrequiredCore date manipulation library; date-fns-tz extends its functionality. Required as a peer dependency.
Agent activity
9 hits · last 30 days
node
6
Resources
date-fns-tz — npm install date-fns-tz · libregistry