date-fns

library4.1.0jsnpmunverified

date-fns is a modern, comprehensive JavaScript utility library designed for manipulating dates in both browser and Node.js environments. The current stable version is 4.1.0. It distinguishes itself by exclusively using native JavaScript `Date` objects, thereby avoiding global object extension, and promoting immutability through its pure functions that consistently return new date instances. The library offers over 200 functions, is highly modular, supports tree-shaking for optimized bundle sizes, and provides first-class TypeScript support with meticulously crafted types. It maintains a consistent and relatively fast release cadence, with major versions v3 and v4 released less than a year apart, aiming to minimize breaking changes in future releases. Additionally, date-fns boasts extensive internationalization capabilities with dozens of available locales.

serialization data

npm install date-fns

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DATE-FNS

date-fns

serializationjavascriptv4.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

format

✓ import { format } from 'date-fns'

✗ const format = require('date-fns')

date-fns primarily uses named exports. Direct default import or CommonJS `require('date-fns')` will not work as expected for individual functions. For CJS, import individual functions directly like `require('date-fns/format')`.

formatInTimeZone

✓ import { formatInTimeZone } from 'date-fns-tz'

✗ import { formatInTimeZone } from 'date-fns'

Time zone functions like `formatInTimeZone` are part of the companion `date-fns-tz` package, which must be installed and imported separately.

enUS

✓ import { enUS } from 'date-fns/locale'

✗ import { enUS } from 'date-fns'

Locale data is imported from the `date-fns/locale` subdirectory to enable tree-shaking and only include necessary locales.

Interval

✓ import type { Interval } from 'date-fns'

TypeScript types for interfaces and utility types are imported using `import type` syntax.

This quickstart demonstrates basic date formatting, sorting with `compareAsc`, adding days with `addDays`, and using `formatInTimeZone` from `date-fns-tz` for time zone conversion.

import { format, compareAsc, addDays } from 'date-fns'; import { formatInTimeZone } from 'date-fns-tz'; const currentDate = new Date(); const futureDate = addDays(currentDate, 7); console.log(`Current date: ${format(currentDate, 'yyyy-MM-dd HH:mm:ss')}`); console.log(`Date one week from now: ${format(futureDate, 'EEEE, LLL do, yyyy')}`); const datesToSort = [ new Date(2023, 0, 15), new Date(2022, 11, 25), new Date(2024, 5, 1), ]; datesToSort.sort(compareAsc); console.log('Sorted dates:', datesToSort.map(d => format(d, 'yyyy-MM-dd'))); // Example with time zone support (requires date-fns-tz) const dateInUTC = new Date('2024-03-08T10:00:00Z'); const formattedInLA = formatInTimeZone(dateInUTC, 'America/Los_Angeles', 'yyyy-MM-dd HH:mm:ss zzz'); console.log(`UTC date in LA time: ${formattedInLA}`);

Debug

Known issues

breakingVersion 4.0.0 introduced first-class time zone support and significant changes. While most API remained stable, all breaking changes are type-related and affect users explicitly utilizing internal date-fns types.

fix

Review TypeScript usage and adapt to updated internal types if directly referencing them. Ensure `date-fns-tz` is installed and updated for time zone functionality.

affects: >=4.0.0

gotchaWhen using time zone functions, you must install and import from the companion `date-fns-tz` package. `TZDate` within this package received critical bug fixes in v1.0.2.

fix

Install `date-fns-tz` (e.g., `npm install date-fns-tz`) and ensure it's at least v1.0.2. Import functions like `formatInTimeZone` from `date-fns-tz`.

affects: >=4.0.0

gotchaIn `format` functions, using protected tokens like `Y` (year in calendar, but ISO week-numbering year for `yyyy`) or `D` (day of year, but day of month for `dd`) without passing a corresponding option can lead to unexpected output.

fix

Always use `yyyy` for year and `dd` for day of month. Consult the documentation for specific token usage and required options, especially for less common formats.

affects: >=3.1.0

breakingAs of v4.1.0, internal `constructFrom` functions now return `Invalid Date` or `NaN` instead of throwing an exception when `null` arguments are passed, even though `null` is not a valid input.

fix

While this fixes unexpected crashes, ensure your code handles `Invalid Date` or `NaN` outputs for potentially malformed date inputs, rather than relying on an exception being thrown for `null`.

affects: >=4.1.0

gotchaEarlier 3.x versions (e.g., 3.3.0, 3.3.1) contained bugs related to Daylight Saving Time (DST) handling and incorrect `Math.floor` vs `Math.trunc` usage, affecting functions like `differenceInCalendarDays`, `getOverlappingDaysInIntervals`, and conversion functions.

fix

Upgrade to the latest stable version (4.x or higher) to benefit from these crucial bug fixes. If remaining on 3.x, ensure you are on at least v3.3.1.

affects: 3.0.0 - 3.3.0

Errors

Common errors & fixes

TypeError: (0 , date_fns__WEBPACK_IMPORTED_MODULE_0__.format) is not a function

This error often occurs when attempting to use CommonJS `require` with named ESM imports in environments configured for modules, or when importing individual functions incorrectly.

fix

For ESM, use `import { functionName } from 'date-fns'`. For CommonJS in older Node.js or build setups, use `const { functionName } = require('date-fns')` or `const functionName = require('date-fns/functionName')` (preferred for tree-shaking).

RangeError: `month` is not in the range 0-11

The native JavaScript `Date` constructor's month argument is zero-indexed (0 for January, 11 for December), a common source of off-by-one errors.

fix

When creating a new `Date` object with `new Date(year, monthIndex, day)`, remember to subtract 1 from the conventional month number (e.g., `new Date(2024, 0, 1)` for January 1, 2024).

Error: A locale must be supplied to a date-fns function

Some date-fns functions, particularly those involving formatting or relative time, require a locale object to determine correct pluralization, day names, etc.

fix

Import the desired locale (e.g., `import { enUS } from 'date-fns/locale'`) and pass it to the function via its options object: `format(date, 'PPP', { locale: enUS })`.

TypeError: formatInTimeZone is not a function

This typically means the `date-fns-tz` package, which provides time zone specific functions, is either not installed or `formatInTimeZone` is being imported from `date-fns` instead of `date-fns-tz`.

fix

First, ensure `date-fns-tz` is installed (`npm install date-fns-tz`). Then, verify the import statement: `import { formatInTimeZone } from 'date-fns-tz'`. Do not import time zone functions directly from `date-fns`.

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

date-fns-tzrequiredRequired for first-class time zone support introduced in v4.0.0. Critical bug fixes in its `TZDate` component (v1.0.2) are essential for stability.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/date-fns/date-fns ↗

packagehttps://www.npmjs.com/package/date-fns ↗

homepagehttps://date-fns.org ↗