# date-fns — Modern Modular JavaScript Date Utility Library

> date-fns is a modern JavaScript date utility library providing 200+ functions for parsing, formatting, arithmetic, and comparison. Tree-shakeable, immutable, TypeScript-first, and the modern alternative to Moment.js.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
npm i date-fns
```

```ts
import { format, formatDistanceToNow, addDays, isAfter, parseISO } from "date-fns";
import { zhCN } from "date-fns/locale";

const now = new Date();

// Format
format(now, "yyyy-MM-dd HH:mm"); // 2026-04-11 14:30
format(now, "PPPP", { locale: zhCN }); // Saturday, April 11, 2026

// Relative
formatDistanceToNow(parseISO("2026-04-01"), { addSuffix: true }); // about 10 days ago

// Arithmetic
const tomorrow = addDays(now, 1);
isAfter(tomorrow, now); // true
```

## Intro

date-fns is a modern JavaScript date utility library with 200+ functions. Unlike Moment.js (which is mutable and class-based), date-fns is functional, immutable, and tree-shakeable — only the functions you import ship in your bundle. The modern, efficient choice for date handling in TS/JS.

- **Repo**: https://github.com/date-fns/date-fns
- **Stars**: 36K+
- **Language**: TypeScript
- **License**: MIT

## What date-fns Does

- **Format** — 50+ format tokens, locale-aware
- **Parse** — strict parsing, ISO, custom formats
- **Arithmetic** — add/sub days, months, years, hours, minutes, weeks
- **Comparison** — isAfter, isBefore, isEqual, closestTo
- **Difference** — differenceInDays/Hours/Minutes
- **Distance** — formatDistance, formatDistanceToNow (relative strings)
- **Locales** — 70+ locales
- **Timezone** — via date-fns-tz adapter
- **Immutable** — every function returns a new Date

## Architecture

Pure functions over native `Date` objects — no classes, no wrappers. Each function is a separate module. Locales are separate imports for tree-shakeability. Types are native TypeScript (not @types).

## Self-Hosting

Client or server library, zero runtime deps.

## Key Features

- 200+ pure functions
- Tree-shakeable (v2+)
- TypeScript native
- 70+ locales
- Immutable
- Small (~15KB with common functions)
- No Moment-style mutable object
- ESM and CJS builds
- Native Date compatible

## Comparison

| Library | Size | API Style | Tree-shake | Timezone |
|---|---|---|---|---|
| date-fns | ~15KB used | Functional | Yes | Via plugin |
| Day.js | ~6KB | Chainable (Moment-like) | Plugins | Via plugin |
| Luxon | ~30KB | OO (classes) | No | Built-in |
| Moment | ~230KB | Mutable classes | No | Built-in |
| Temporal (TC39) | Native | Modern API | N/A | Native |

## FAQ

**Q: date-fns or Day.js — which should I choose?**
A: date-fns is more functional and tree-shakes better; Day.js feels more like Moment with a smoother chainable API. It comes down to personal preference.

**Q: How do I handle timezones?**
A: Use the `date-fns-tz` companion package, which provides `zonedTimeToUtc`, `formatInTimeZone`, and more.

**Q: Will I not need it once Temporal ships?**
A: Temporal isn't fully landed yet (Safari has partial support) and the polyfill is ~60KB. date-fns will remain mainstream for the foreseeable future.

## Sources & Credits

- Docs: https://date-fns.org
- GitHub: https://github.com/date-fns/date-fns
- License: MIT

---
Source: https://tokrepo.com/en/workflows/date-fns-modern-modular-javascript-date-utility-library-3ae90928
Author: AI Open Source