date-fns

Modern JavaScript date utility library

weekly downloads43.3M

versionv4.1.0

licenseMIT

categoryutility

Overview

date-fns is a comprehensive JavaScript date utility library offering over 200 pure, immutable functions for parsing, formatting, and manipulating dates. With 43+ million weekly downloads, it's become the go-to alternative to Moment.js for developers who need powerful date operations without the bundle size penalty. Every function works directly with native JavaScript Date objects and returns new instances rather than mutating inputs, making it predictable and safe for functional programming patterns.

The library's modular architecture is its defining feature. Unlike monolithic date libraries, date-fns allows you to import only the specific functions you need (e.g., import { format, addDays } from 'date-fns'), enabling build tools like webpack and Rollup to tree-shake unused code. This results in significantly smaller production bundles—often just a few kilobytes versus 70kB+ for alternatives. Version 4.0 introduced first-class time zone support through a companion package, addressing one of JavaScript's most notorious pain points.

date-fns is used across the JavaScript ecosystem, from frontend frameworks (React, Vue, Angular) to Node.js backends and serverless functions. Its functional API, full TypeScript support, and comprehensive i18n capabilities (dozens of locales) make it suitable for both simple date formatting tasks and complex business logic involving date calculations, comparisons, and timezone conversions. The library maintains backward compatibility while actively evolving, with a strong focus on developer experience and performance.

Quick Start

typescript

import { format, addDays, differenceInDays, isWithinInterval, parseISO } from 'date-fns';
import { enUS, es } from 'date-fns/locale';

const today = new Date();
const futureDate = addDays(today, 14);

console.log(format(futureDate, 'MMMM do, yyyy', { locale: enUS }));
console.log(format(futureDate, 'MMMM do, yyyy', { locale: es }));

const daysDiff = differenceInDays(futureDate, today);
console.log(`Days until deadline: ${daysDiff}`);

const apiDateString = '2024-12-15T10:30:00Z';
const parsedDate = parseISO(apiDateString);

const validRange = isWithinInterval(parsedDate, {
  start: new Date(2024, 11, 1),
  end: new Date(2024, 11, 31)
});

console.log(`Date is in December 2024: ${validRange}`);

const formattedForAPI = format(today, "yyyy-MM-dd'T'HH:mm:ss'Z'");
console.log(`API format: ${formattedForAPI}`);

Use Cases

Form validation and user input processing: Parsing user-submitted dates in various formats, validating date ranges for booking systems, and ensuring dates fall within business rules (e.g., isAfter(selectedDate, new Date()) to prevent past dates in reservation forms).

Calendar and scheduling applications: Building calendar views with functions like startOfWeek, endOfMonth, eachDayOfInterval to generate date ranges, and addMonths/subDays for navigation. Calculating business day differences or formatting events with locale-specific patterns.

Data visualization and analytics dashboards: Grouping time-series data by intervals using startOfDay, startOfHour, formatting axis labels with consistent patterns, and calculating relative time differences (e.g., formatDistanceToNow for "2 hours ago" labels).

API response formatting: Transforming database timestamps into user-friendly formats across multiple locales, handling UTC conversions with the TZ package, and ensuring consistent date serialization in REST or GraphQL responses.

Report generation and business logic: Calculating fiscal quarters with getQuarter, determining working days between dates with differenceInBusinessDays, and generating period-over-period comparisons for financial reports or SaaS analytics.

Pros & Cons

Pros

+Exceptional tree-shaking support reduces bundle size to only imported functions, often resulting in 90%+ smaller builds compared to Moment.js
+Immutable, pure functions eliminate side effects and make code predictable, with no prototype pollution or global state mutations
+Comprehensive function library (200+) covers nearly every date operation including parsing, formatting, arithmetic, comparisons, and intervals
+First-class TypeScript support with accurate types and full IntelliSense, plus v4 brings proper time zone handling via date-fns-tz integration
+Active maintenance and modern codebase with excellent documentation, locale support for i18n, and consistent functional API design

Cons

−More verbose import syntax compared to chainable APIs—each function requires explicit import, which can clutter imports for complex date logic
−Time zone support requires a separate package (date-fns-tz) and isn't as seamless as libraries built with TZ as a core feature
−Steeper learning curve for developers accustomed to method chaining (Moment/Day.js style), requiring mental shift to functional composition
−No built-in locale data—each locale must be imported separately, adding manual configuration overhead for multi-language apps
−Breaking changes between major versions (v2 to v3, v3 to v4) require migration effort for large codebases

Alternatives

dayjsv1.11.19

2KB immutable date time library alternative to Moment.js with the same modern API

utilitydayjsdate

34.7M / week

luxonv3.7.2

Immutable date wrapper

utilitydateimmutable

20.4M / week

Comparisons

Install

bash

npm install date-fns

bash

pnpm add date-fns

bash

bun add date-fns

Overview

Quick Start

typescript

import { format, addDays, differenceInDays, isWithinInterval, parseISO } from 'date-fns';
import { enUS, es } from 'date-fns/locale';

const today = new Date();
const futureDate = addDays(today, 14);

console.log(format(futureDate, 'MMMM do, yyyy', { locale: enUS }));
console.log(format(futureDate, 'MMMM do, yyyy', { locale: es }));

const daysDiff = differenceInDays(futureDate, today);
console.log(`Days until deadline: ${daysDiff}`);

const apiDateString = '2024-12-15T10:30:00Z';
const parsedDate = parseISO(apiDateString);

const validRange = isWithinInterval(parsedDate, {
  start: new Date(2024, 11, 1),
  end: new Date(2024, 11, 31)
});

console.log(`Date is in December 2024: ${validRange}`);

const formattedForAPI = format(today, "yyyy-MM-dd'T'HH:mm:ss'Z'");
console.log(`API format: ${formattedForAPI}`);

Use Cases

Pros & Cons

Pros

+Exceptional tree-shaking support reduces bundle size to only imported functions, often resulting in 90%+ smaller builds compared to Moment.js
+Immutable, pure functions eliminate side effects and make code predictable, with no prototype pollution or global state mutations
+Comprehensive function library (200+) covers nearly every date operation including parsing, formatting, arithmetic, comparisons, and intervals
+First-class TypeScript support with accurate types and full IntelliSense, plus v4 brings proper time zone handling via date-fns-tz integration
+Active maintenance and modern codebase with excellent documentation, locale support for i18n, and consistent functional API design

Cons

−More verbose import syntax compared to chainable APIs—each function requires explicit import, which can clutter imports for complex date logic
−Time zone support requires a separate package (date-fns-tz) and isn't as seamless as libraries built with TZ as a core feature
−Steeper learning curve for developers accustomed to method chaining (Moment/Day.js style), requiring mental shift to functional composition
−No built-in locale data—each locale must be imported separately, adding manual configuration overhead for multi-language apps
−Breaking changes between major versions (v2 to v3, v3 to v4) require migration effort for large codebases