@date-fns/utc

@date-fns/utc

The package provides Date extensions UTCDate and UTCDateMini that perform all calculations in UTC rather than the system time zone.

Using it makes date-fns operate in UTC but can be also used without it.

Like everything else in the date-fns ecosystem, the library is build-size aware. The smallest component, UTCDateMini, is only 239 B.

Need more than just UTC? See @date-fns/tz that provides full time zone support.

Installation

npm install @date-fns/utc --save

Usage

UTCDate and UTCDateMini have API identical to Date, but perform all calculations in UTC, which might be essential when calculating abstract date-time, i.e for rendering chart or calendar component:

import { UTCDate } from "@date-fns/utc";
import { addHours } from "date-fns";

// Given that the system time zone is America/Los_Angeles
// where DST happens at Sunday, 13 March 2022, 02:00:00

// Using system time zone will produce 03:00 instead of 02:00 because of DST:
const date = new Date(2022, 2, 13);
addHours(date, 2).toString();
//=> 'Sun Mar 13 2022 03:00:00 GMT-0700 (Pacific Daylight Time)'

// Using UTC will provide expected 02:00:
const utcDate = new UTCDate(2022, 2, 13);
addHours(utcDate, 2).toString();
//=> 'Sun Mar 13 2022 02:00:00 GMT+0000 (Coordinated Universal Time)'

Difference between UTCDate and UTCDateMini

The main difference between UTCDate and UTCDateMini is the build footprint. The UTCDateMini is 239 B, and the UTCDate is 504 B. While the difference is slight, and 504 B is not significant by any means, it might be essential in some environments and use cases.

Unlike UTCDateMini which implements only getters, setters, and getTimezoneOffset, UTCDate also provides formatter functions, mirroring all original Date functionality:

import { UTCDateMini, UTCDate } from "@date-fns/utc";

// UTCDateMini will format date-time in the system time zone:
new UTCDateMini(2022, 2, 13).toString();
//=> 'Sat Mar 12 2022 16:00:00 GMT-0800 (Pacific Standard Time)'

// UTCDate will format date-time in the UTC, like expected:
new UTCDate(2022, 2, 13).toString();
//=> 'Sun Mar 13 2022 00:00:00 GMT+0000 (Coordinated Universal Time)'

Even though UTCDate has a complete API, developers rarely use the formatter functions outside of debugging, so we recommend you pick the more lightweight UTCDateMini for internal use. However, in environments you don't control, i.e., when you expose the date from a library, using UTCDate will be a safer choice.

API

• UTCDate
• utc

UTCDate

UTCDate mirrors all the Date API, so refer to the MDN documentation for the full list of methods and properties.

utc

The utc function allows to specify the context for the date-fns functions (starting from date-fns@4):

import { isSameDay } from "date-fns";
import { utc } from "@date-fns/utc";

isSameDay("2024-09-09T23:00:00-04:00", "2024-09-10T10:00:00+08:00", {
  in: utc,
});
//=> true

Changelog

See the changelog.

License

MIT © Sasha Koss

Changelog

v2.1.0 - 2024-09-14

Added

• Added more documentation to the README.md file and JSDoc.