date-fns
Modular date utilities — import only the functions you use, no wrapper object.
What it is
date-fns is a modern JavaScript library that provides comprehensive, lightweight, and modular functions for parsing, formatting, manipulating, and comparing dates.
date-fns provides over 200 functions for working with dates, including formatting, parsing, difference calculations, comparisons, adding or subtracting time, and more. Functions are pure and immutable, returning new date objects rather than modifying existing ones.
- Licence
- MIT
- Best known for
- Tree-shakeable, immutable functions over native Date
When to use it
The question documentation cannot answer for you — because it cannot recommend something else.
Reach for it when
- You need date arithmetic and formatting with a small bundle footprint
- You prefer plain `Date` objects over a custom wrapper type
Look elsewhere when
- You need deep timezone handling — Luxon or Temporal is stronger there
Installation
npm install date-fnsGetting started
The smallest useful thing you can do with it, and what each part means.
import { format } from 'date-fns';
const result = format(new Date(2025, 7, 22), 'yyyy-MM-dd');
console.log(result); // '2025-08-22'import { parse } from 'date-fns';
const result = parse('2025-08-22', 'yyyy-MM-dd', new Date());
console.log(result);Advanced usage
Where the library earns its place over a simpler alternative.
import { addDays, subMonths } from 'date-fns';
const today = new Date();
console.log(addDays(today, 5));
console.log(subMonths(today, 2));import { differenceInDays } from 'date-fns';
const start = new Date(2025, 7, 1);
const end = new Date(2025, 7, 22);
console.log(differenceInDays(end, start)); // 21import { isBefore, isAfter } from 'date-fns';
const d1 = new Date(2025, 7, 1);
const d2 = new Date(2025, 7, 22);
console.log(isBefore(d1, d2)); // true
console.log(isAfter(d2, d1)); // trueimport { startOfMonth, endOfMonth } from 'date-fns';
const today = new Date(2025, 7, 22);
console.log(startOfMonth(today));
console.log(endOfMonth(today));Errors and fixes
The failures you are most likely to hit, and what actually resolves them.
- Invalid Date
- Ensure the input is a valid Date object or properly formatted string. Use `isValid(date)` to check before processing.
- Parsing errors
- Ensure the string matches the format exactly when using `parse()`.
Best practices
- Import only the functions you need to reduce bundle size (tree-shaking).
- Use pure functions to avoid mutating original Date objects.
- Always provide a fallback Date for parsing when using `parse`.
- Use UTC functions when working across time zones to avoid inconsistencies.
- Combine with other date-fns utilities for cleaner and more readable date manipulations.
Alternatives
Comparable options, and the reason you would pick one over the other.
Background
Why it exists, and what it was reacting to.
date-fns was created to provide a functional, immutable, and tree-shakable alternative to libraries like Moment.js. Each function in date-fns is independent, allowing developers to import only what they need, resulting in smaller bundle sizes and better performance.