date-fns-tz

date-fns-tz is a complementary library for date-fns that adds first-class IANA time zone handling on top of the plain JavaScript Date objects date-fns works with. It leans on the browser and Node.js Intl API to resolve time zone offsets and names, so no multi-megabyte time zone database needs to ship in your bundle.

It provides a small set of focused helpers: format a date in any target time zone, convert between UTC and a zoned wall-clock time, and read the offset for a given zone and instant. This makes it straightforward to display and accept times in a fixed time zone regardless of where a user or server actually is.

What You Get

• A formatInTimeZone helper that renders any date in a specified IANA zone regardless of the system time zone, with full z..zzzz token support.
• Conversion helpers fromZonedTime and toZonedTime to move between UTC instants and zoned wall-clock Date values.
• A getTimezoneOffset helper returning the UTC offset in milliseconds for a zone and instant, correctly accounting for DST.
• Both CommonJS and native ESM entry points, plus an fp functional-programming variant of every function.

Common Use Cases

• Displaying an event’s start time in the venue’s local time zone to users anywhere in the world.
• Converting a date picker value plus a selected IANA zone into the correct UTC instant to send to a server.
• Rendering server-provided UTC timestamps as local wall-clock times for a specific target zone.
• Formatting timestamps with proper short/long time zone names like EST or Eastern Standard Time.

Under The Hood

Architecture — The public surface is a handful of pure functions organized one-per-directory under src/ (formatInTimeZone, fromZonedTime, toZonedTime, getTimezoneOffset, format, toDate), each re-exported from src/index.ts. The core of the time zone logic lives in src/_lib, where tzParseTimezone resolves an offset for a zone and instant, tzTokenizeDate and tzIntlTimeZoneName call the Intl DateTimeFormat API to extract zone parts and names, and newDateUTC/getTimezoneOffsetInMilliseconds handle the arithmetic. toZonedTime parses the input via toDate, computes the offset through tzParseTimezone, and shifts the Date so its local getters reflect the target zone; formatInTimeZone composes toZonedTime with the extended format. Tech Stack — Written in TypeScript, compiled to both CommonJS and ESM via two tsconfig targets, with date-fns (^3.0.0 || ^4.0.0) as the sole peer dependency. It relies entirely on the platform Intl API for zone data, so it carries no runtime dependencies of its own. Tooling is ESLint, Prettier, Karma for the browser test runner, and CircleCI. Code Quality — Every function directory ships a co-located test.js, and shared internals under _lib each have their own test suite, indicating solid coverage of the offset and formatting logic. Source files carry detailed JSDoc with @throws contracts and worked examples, and the code favors small pure functions with explicit RangeError/TypeError handling for invalid dates and zones. API Design — The API is deliberately minimal and mirrors date-fns naming conventions, so formatInTimeZone reads like a natural extension of format. For most applications a single function call is enough, options objects are optional, and an fp build offers curried variants for functional pipelines. The README documents each function with signatures and runnable examples, keeping the learning curve low for anyone already using date-fns.