date-fns

Overview

date-fns is a JavaScript library that provides a collection of functions for manipulating and formatting dates. Established in 2014, the library distinguishes itself by working directly with native JavaScript Date objects, avoiding the creation of custom wrapper objects. This design choice contributes to predictable behavior and interoperability within existing JavaScript environments. The library adopts a modular approach, where each function is an independent entity. This architecture allows developers to import only the specific functions required for a task, which facilitates tree-shaking for optimized bundle sizes in modern build processes. For example, if an application only needs to format a date, only the format function and its dependencies are included, rather than the entire library. This is particularly beneficial for single-page applications and other web projects where minimizing asset size is a priority.

The library's design adheres to a functional programming paradigm, meaning its functions are pure and immutable. They do not modify the original Date object passed as an argument; instead, they return a new Date object with the applied changes. This immutability helps prevent side effects and makes date-related logic easier to test and reason about. date-fns offers broad internationalization support, providing locales for various languages and regional date formats. This enables developers to create applications that display dates and times appropriately for users across different geographical locations, a critical feature for global applications. The library is compatible with modern JavaScript environments, including Node.js and all major browsers. It also provides full TypeScript support, offering type definitions for enhanced developer experience and compile-time error checking.

Developers choose date-fns for projects that require precise control over date operations, a minimal footprint, and a functional coding style. Its comprehensive API covers a wide array of date-related tasks, from simple formatting and parsing to complex calculations like adding durations, finding the difference between dates, and working with time zones. The library's commitment to using native Date objects and its modular design make it a suitable choice for projects aiming for performance and maintainability. Its extensive documentation and examples on the date-fns official documentation site further support its adoption by developers.

Key features

• Modular Architecture: Each function is standalone, allowing developers to import only necessary parts, which supports tree-shaking for smaller application bundles.
• Native Date Objects: Works directly with JavaScript's built-in Date objects, avoiding custom wrapper classes and ensuring compatibility with existing date utilities.
• Functional Programming Style: Functions are pure and immutable, meaning they do not modify original date objects but return new ones, promoting predictable code and easier debugging.
• Comprehensive API: Offers over 200 functions for various date operations, including formatting, parsing, adding/subtracting time units, comparing dates, and calculating durations.
• Internationalization (i18n): Provides extensive locale support, enabling developers to format and parse dates according to different language and regional conventions.
• TypeScript Support: Includes full TypeScript definitions, enhancing type safety and developer experience in TypeScript projects.
• Time Zone Interoperability: Functions are designed to work effectively with JavaScript's native handling of time zones, although explicit time zone conversion often requires additional libraries due to the native Date object's limitations.
• Zero-Dependency: The core library has no external dependencies, contributing to its light footprint and ease of integration into projects.

Pricing

As of June 2026, date-fns is a free and open-source library. It is distributed under the MIT License, which permits use, modification, and distribution in both commercial and non-commercial projects without cost. There are no paid tiers, subscriptions, or premium features associated with the core date-fns library.

Common integrations

date-fns integrates seamlessly into most modern JavaScript development environments due to its native Date object usage and modular design. Its common integrations include:

• React and other UI frameworks: Used within React, Vue, Angular, and Svelte components for displaying, formatting, and calculating dates based on user input or data fetching. Its small bundle size makes it suitable for front-end applications.
• Node.js Backend Services: Employed in server-side applications for data processing, database interactions involving date fields, scheduling tasks, and generating reports.
• Build Tools (Webpack, Rollup, Parcel): Its tree-shakeable nature is optimized by modern bundlers like Webpack, Rollup, and Parcel for efficient code splitting and smaller final bundles. This ensures only the code that is actively used gets included in the production build.
• TypeScript Projects: Fully compatible with TypeScript, providing type definitions that ensure type safety and improved developer experience during development.
• Testing Frameworks (Jest, Mocha): Can be used with popular JavaScript testing frameworks to create mock dates or verify date-related logic in unit and integration tests.

Alternatives

While date-fns offers specific advantages, several other libraries address date and time manipulation in JavaScript:

• Moment.js: A widely used, mature library known for its mutable wrapper objects and extensive plugin ecosystem, though it is no longer under active development for new features.
• Luxon: Developed by the Moment.js team, Luxon is an immutable, modern alternative that leverages the native Intl API for advanced internationalization and time zone handling.
• Day.js: A minimalist library designed to be a lightweight alternative to Moment.js, featuring a similar API but with a smaller footprint and immutable objects.
• Native JavaScript Date object: For very basic date operations, developers can use the built-in Date object directly, though it lacks many convenience functions for formatting, parsing, and complex calculations.

Getting started

To begin using date-fns, install it via npm or yarn. This example demonstrates how to format a date and calculate the difference between two dates.

// 1. Install date-fns
npm install date-fns

// 2. Import specific functions
import { format, differenceInDays, addDays } from 'date-fns';

// 3. Use the functions

// Get the current date
const today = new Date(); // e.g., Tue Jun 01 2026 10:00:00 GMT-0700 (Pacific Daylight Time)

// Format the date
const formattedDate = format(today, 'yyyy-MM-dd');
console.log(`Formatted today: ${formattedDate}`); // Output: Formatted today: 2026-06-01

// Add days to a date
const futureDate = addDays(today, 7);
const formattedFutureDate = format(futureDate, 'EEEE, MMMM do, yyyy');
console.log(`One week from now: ${formattedFutureDate}`); // Output: One week from now: Tuesday, June 08th, 2026

// Calculate the difference between two dates
const startDate = new Date(2026, 0, 1); // January 1, 2026
const endDate = new Date(2026, 0, 31); // January 31, 2026
const daysDifference = differenceInDays(endDate, startDate);
console.log(`Days between January 1st and January 31st: ${daysDifference}`); // Output: Days between January 1st and January 31st: 30

// Example with internationalization (requires importing a locale)
import { enUS, es } from 'date-fns/locale';

const dateToLocalize = new Date(2026, 5, 23);
const formattedInEnglish = format(dateToLocalize, 'PPPP', { locale: enUS });
const formattedInSpanish = format(dateToLocalize, 'PPPP', { locale: es });

console.log(`English format: ${formattedInEnglish}`); // Output: English format: Tuesday, June 23rd, 2026
console.log(`Spanish format: ${formattedInSpanish}`); // Output: Spanish format: martes, 23 de junio de 2026