date-fns

date-fns is a modular, TypeScript-first utility library that provides more than 200 pure functions for parsing, formatting, comparing, and manipulating JavaScript dates. Rather than extending the native Date prototype, every function accepts and returns plain Date instances, keeping behavior predictable and safe to mix with other libraries.

Each function lives in its own submodule, so bundlers can tree-shake unused code and applications only ship the date logic they actually import. The library ships first-class time zone support through companion packages (@date-fns/tz and @date-fns/utc), dozens of locales for internationalized formatting, and an opt-in functional-programming (fp) variant for point-free composition.

What You Get

• 200+ granular functions (add/sub, compare, diff, format, parse, start/end-of-period, and more), each independently importable
• First-class, immutable time zone handling via the companion @date-fns/tz (TZDate) and @date-fns/utc (UTCDate) packages
• Dozens of locale packs for internationalized month/day names, relative-time phrasing, and formatting
• A functional-programming build (date-fns/fp) with curried, data-last function signatures for composition
• Full TypeScript definitions generated alongside the source, with generics that preserve custom Date subclasses through the call chain

Common Use Cases

• Formatting and parsing dates for display in web and Node.js applications
• Computing durations, differences, and business-day math (e.g. invoice due dates, SLA windows)
• Normalizing and comparing dates across time zones in scheduling or booking systems
• Building calendar and date-picker UI components that need start/end-of-period helpers
• Localizing date and relative-time strings for internationalized products

Under The Hood

Architecture

date-fns is organized as a pnpm monorepo (pkgs/core, pkgs/tz, pkgs/utc, pkgs/docs, pkgs/dev) where the npm date-fns package maps to pkgs/core. Inside pkgs/core/src, each of the 253 exported functions (e.g. addDays, format, differenceInCalendarDays) lives in its own directory with an index.ts implementation and a colocated test.ts, giving the library a flat, highly navigable structure instead of a monolithic module. Cross-cutting behavior is centralized in _lib (formatters, default locale/options, protected-token warnings) and in toDate/constructFrom, which every function routes Date arguments through; constructFrom inspects a Symbol.for("constructDateFrom") on the reference date to decide which constructor to use, which is the mechanism that lets the separate @date-fns/tz (TZDate) and @date-fns/utc (UTCDate) packages plug into the same generic function set without date-fns/core depending on them directly. A parallel src/fp tree (399 files) wraps the same functions in curried, data-last signatures for functional-style composition, and src/locale (98 entries) supplies per-locale formatting data consumed by format/formatDistance at the _lib layer.

Tech Stack

The project is TypeScript-first (96%+ of the codebase) targeting both ESM (index.js) and CJS (index.cjs) output, declared via exports maps with one subpath per function for granular imports and tree-shaking. Tooling is notably modern: oxlint/oxfmt (Rust-based lint/format, replacing ESLint/Prettier) with oxlint-tsgolint for TypeScript-aware linting, @typescript/native-preview (the Go-based tsgo compiler preview), vitest for the test runner, and mise for task/toolchain orchestration in place of npm scripts. The package has zero runtime dependencies, keeping the dependency footprint minimal for consumers. Companion packages @date-fns/tz and @date-fns/utc are versioned and published separately from core within the same monorepo.

Code Quality

Test coverage is essentially 1:1 with the public API: 253 test.ts files sit alongside 253 function implementations in pkgs/core/src, and tests (e.g. addDays/test.ts) cover not just nominal behavior but DST-transition edge cases via a shared getDstTransitions helper and cross-checks against the @date-fns/tz/@date-fns/utc extension types using assertType. Functions are consistently small and single-purpose (most implementation files are well under 50 lines), naming is systematic across the whole API surface (addX/subX, differenceInX, startOfX/endOfX, isX), and every export carries a structured JSDoc block (@summary, @param, @returns, @example) that doubles as the source for the published docs site. Invalid input is handled explicitly and predictably — e.g. addDays short-circuits to NaN-dated output via constructFrom when passed a NaN amount rather than throwing or silently producing a wrong date.

API Design

The API favors small, guessable, single-purpose functions over a chained or class-based interface, which keeps the learning curve shallow for any one function while the sheer surface area (200+ exports) is the main ramp-up cost for the full library. Getting started requires zero boilerplate: import { format } from "date-fns"; format(new Date(), "yyyy-MM-dd") is a complete, working example, and every function’s JSDoc ships a runnable @example. Consistent naming conventions (addX/subX, isX, startOfX) mean that once a developer learns one family of functions, the rest are largely inferable. The optional options?.in context parameter and generic DateType/ResultDate type parameters let advanced users opt into time zone-aware types without imposing that complexity on basic usage, and the separate fp entry point serves functional-style consumers without complicating the default API.