{"id":16003,"library":"date-fns-tz","title":"date-fns Time Zone Support","description":"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.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/marnusw/date-fns-tz","tags":["javascript","date-fns","timezone","time zone","date","time","parse","format","immutable","typescript"],"install":[{"cmd":"npm install date-fns-tz","lang":"bash","label":"npm"},{"cmd":"yarn add date-fns-tz","lang":"bash","label":"yarn"},{"cmd":"pnpm add date-fns-tz","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core date manipulation library; date-fns-tz extends its functionality. Required as a peer dependency.","package":"date-fns","optional":false}],"imports":[{"note":"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.","wrong":"const { formatInTimeZone } = require('date-fns-tz')","symbol":"formatInTimeZone","correct":"import { formatInTimeZone } from 'date-fns-tz'"},{"note":"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.","wrong":"import { utcToZonedTime } from 'date-fns-tz'","symbol":"toZonedTime","correct":"import { toZonedTime } from 'date-fns-tz'"},{"note":"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.","wrong":"import { zonedTimeToUtc } from 'date-fns-tz'","symbol":"fromZonedTime","correct":"import { fromZonedTime } from 'date-fns-tz'"},{"note":"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.","symbol":"format","correct":"import { format } from 'date-fns-tz'"}],"quickstart":{"code":"import { formatInTimeZone, toZonedTime } from 'date-fns-tz';\nimport { parseISO, format } from 'date-fns';\n\nconst dateString = '2024-04-21T18:30:00Z'; // UTC date string\nconst timeZone = 'America/Los_Angeles';\n\n// Parse the ISO string to a Date object (which will be in UTC internally)\nconst utcDate = parseISO(dateString);\n\n// Format the UTC date directly into the target timezone\nconst formattedTimeInLA = formatInTimeZone(utcDate, timeZone, 'yyyy-MM-dd HH:mm:ss zzz');\n\n// Convert the UTC date to a Zoned Date object (representing local time in LA)\nconst zonedDateInLA = toZonedTime(utcDate, timeZone);\n\n// Format the zoned date using date-fns's format (since it's now a 'local' date in LA)\nconst formattedZonedDate = format(zonedDateInLA, 'yyyy-MM-dd HH:mm:ss');\n\nconsole.log(`Original UTC: ${dateString}`);\nconsole.log(`Formatted in ${timeZone} (with timezone token): ${formattedTimeInLA}`);\nconsole.log(`Zoned Date in ${timeZone}: ${zonedDateInLA.toISOString()}`); // Shows as if local time, but internally still UTC\nconsole.log(`Formatted Zoned Date in ${timeZone}: ${formattedZonedDate}`);\n","lang":"typescript","description":"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`."},"warnings":[{"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).","message":"date-fns-tz v3.0.0 removed support for date-fns v2. Ensure your project uses date-fns v3 or v4.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Globally search and replace `utcToZonedTime` with `toZonedTime` and `zonedTimeToUtc` with `fromZonedTime` in your codebase.","message":"Functions `utcToZonedTime` and `zonedTimeToUtc` were renamed to `toZonedTime` and `fromZonedTime` respectively in v3.0.0.","severity":"breaking","affected_versions":">=3.0.0"},{"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')`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Install `date-fns` explicitly: `npm install date-fns`. Check `package.json` for compatible versions if you encounter issues.","message":"The `date-fns` dependency is a peer dependency. You must install `date-fns` separately and ensure its version is compatible with `date-fns-tz`.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure the runtime environment supports `Intl.DateTimeFormat` or include a polyfill (e.g., `@formatjs/intl-datetimeformat`).","cause":"The `Intl.DateTimeFormat` API is not available or incomplete in the current JavaScript environment.","error":"TypeError: Cannot read properties of undefined (reading 'formatToParts')"},{"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.","cause":"Incorrect import statement or module resolution configuration for a hybrid ESM/CJS package.","error":"Error: date-fns-tz is an ESM-only package and cannot be used in CommonJS. (Or similar import/require errors)"},{"fix":"Update the function call to the new names: `toZonedTime` and `fromZonedTime`.","cause":"Attempting to use the old `utcToZonedTime` or `zonedTimeToUtc` function name after upgrading to v3.0.0+.","error":"TypeError: (0 , date_fns_tz__WEBPACK_IMPORTED_MODULE_3__.utcToZonedTime) is not a function"},{"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).","cause":"Attempting to use a default import for a function that is exported as a named export.","error":"TypeError: (0 , date_fns_tz__WEBPACK_IMPORTED_MODULE_3__.default) is not a function (or similar error indicating default import issue)"}],"ecosystem":"npm"}