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-tzVerified import paths — ran on the pinned version, not inferred.
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`.
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).
Globally search and replace `utcToZonedTime` with `toZonedTime` and `zonedTimeToUtc` with `fromZonedTime` in your codebase.
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')`.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.
Install `date-fns` explicitly: `npm install date-fns`. Check `package.json` for compatible versions if you encounter issues.
Ensure the runtime environment supports `Intl.DateTimeFormat` or include a polyfill (e.g., `@formatjs/intl-datetimeformat`).
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.Update the function call to the new names: `toZonedTime` and `fromZonedTime`.
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).