npmIntermediate

date-fns

Modern JavaScript date utility library

datetimeformattingimmutabletree-shakabletypescriptdate-fnshacktoberfestjavascriptmodules

The Problem

Moment.js normalised date handling in JavaScript but became monolithic — even importing one function loads the entire 67KB library. Immutability was bolted on, timezone support required a separate plugin, and the maintainers officially marked it as legacy. date-fns was designed from the start as a collection of pure functions, one file per function.

Mental Model

Every date-fns function is a standalone export: import { format, addDays, differenceInCalendarDays } from 'date-fns'. Each function takes a plain Date and returns a new Date or a primitive — no classes, no mutation, no chaining. Your bundler tree-shakes everything you don't import, so you pay only for what you use.

60-second start

Install date-fns

npm install date-fns
import { } from 'date-fns';

Use it when

Use date-fns for formatting, parsing, arithmetic (add/subtract days, months, years), comparison, and locale-aware output in any JavaScript environment. Import only what you need and the bundle impact is minimal.

Skip it when

date-fns v2 has limited first-party timezone support — for complex timezone-aware applications use Luxon or the Temporal polyfill. The function-heavy API can feel verbose for simple one-liners; Day.js's method chaining is more readable in those cases.

Alternatives

dayjs2KB with a fluent chaining API — better for simple formatting and arithmetic without needing tree-shaking

luxonBest-in-class timezone support via the Intl API — worth the larger bundle for international applications

TemporalTC39 built-in for dates and times — available via polyfill, will eventually replace all date libraries

Ready to explore the full API?

See every class, function, and relationship in an interactive graph.