date-fns

4.1.0 · active · verified Sat Apr 18

date-fns is a modern, modular JavaScript utility library providing over 200 functions for manipulating dates in browsers and Node.js. It operates on native `Date` objects, ensuring immutability and purity, and offers full TypeScript support and internationalization. The current stable version is 4.1.0, which includes first-class time zone support (introduced in v4.0.0), and the project maintains a faster release cadence compared to earlier major versions.

Common errors

```
TypeError: date-fns function received null or undefined argument
```
cause Internal `constructFrom` function throwing an exception when `null` (which is not allowed) is passed to date-fns functions.

fix Upgrade to date-fns v4.1.0 or later. Ensure only valid `Date` objects or parseable date strings are passed to date-fns functions.
```
getOverlappingDaysInIntervals returns 0 unexpectedly
```
cause A bug in `getOverlappingDaysInIntervals` caused by incorrect sorting of interval components leading to an incorrect result of 0.

fix Upgrade to date-fns v3.3.0 or later to fix the sorting issue.
```
areIntervalsOverlapping returns false for clearly overlapping intervals
```
cause A bug in `areIntervalsOverlapping` caused by incorrect sorting of the input intervals.

fix Upgrade to date-fns v3.0.6 or later to ensure correct interval comparisons.
```
Incorrect day count from differenceInCalendarDays or similar date-fns functions
```
cause Functions like `differenceInCalendarDays`, `getISOWeek`, `getWeek` in v3.3.0 incorrectly used `trunc` instead of `round` for calculations.

fix Upgrade to date-fns v3.3.1 or later to resolve the calculation errors.
```
TypeScript types for date-fns not compatible with Lodash flow or fp-ts pipe
```
cause Type compatibility issues with higher-order functions from utility libraries like Lodash's `flow` or fp-ts's `pipe`.

fix Upgrade to date-fns v3.2.0 or later to get improved type compatibility.

Warnings

breaking Time zone functions (introduced in v4.0) require `@date-fns/tz` v1.0.2 for critical bug fixes and full functionality.
Fix: Upgrade `@date-fns/tz` to v1.0.2 or higher alongside date-fns v4.1.0+.
breaking v4.0.0 introduced type-related breaking changes that primarily affect users explicitly relying on date-fns internal types.
Fix: Review type definitions when upgrading to v4.0.0 if your codebase interacts with internal date-fns types.
gotcha Functions like `differenceInCalendarDays`, `getISOWeek`, and `getWeek` in v3.3.0 had calculation bugs due to incorrectly using `trunc` instead of `round`.
Fix: Upgrade to v3.3.1 or higher to resolve incorrect calculations in affected functions.
gotcha DST (Daylight Saving Time) issues in `getOverlappingDaysInIntervals` in v3.3.0 and prior could lead to inconsistent day counts.
Fix: Upgrade to v3.3.1 or higher for correct DST handling in `getOverlappingDaysInIntervals`.
gotcha Using protected tokens (e.g., `Y`, `D`) in `format` strings without passing a corresponding option can lead to unexpected behavior.
Fix: Consult the documentation for `format` to use correct tokens or provide necessary options to avoid unintended behavior with protected tokens.

Install

npm install date-fns npm
yarn add date-fns yarn
pnpm add date-fns pnpm

Imports

format

wrong:

const { format } = require('date-fns')

correct:

import { format } from 'date-fns'

date-fns is ESM-only since v3.

Quickstart

This quickstart demonstrates how to use `format` to reformat a date string and `compareAsc` to sort an array of `Date` objects.

import { compareAsc, format } from "date-fns";

// Format a specific date
console.log(format(new Date(2014, 1, 11), "yyyy-MM-dd"));
//=> '2014-02-11'

// Sort an array of dates
const dates = [
  new Date(1995, 6, 2),
  new Date(1987, 1, 11),
  new Date(1989, 6, 10),
];
dates.sort(compareAsc);
console.log(dates);
//=> [
//   Wed Feb 11 1987 00:00:00 GMT+...,
//   Mon Jul 10 1989 00:00:00 GMT+...,
//   Sun Jul 02 1995 00:00:00 GMT+...
// ]

view raw JSON →