web-utilities-date-fns

date-fns Date Utility Patterns

Quick Guide: Use date-fns for modular, tree-shakeable date operations. Import only what you need. Use parseISO for ISO strings, format with Unicode tokens for display, and pure functions that return new Date objects. For timezones, use @date-fns/tz with TZDate (v4+) or date-fns-tz with formatInTimeZone (v3.x). Never mutate dates.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use parseISO() for ISO 8601 strings - NEVER use new Date(string) which has browser inconsistencies)

**(You MUST import only needed functions - NEVER use import * as dateFns which defeats tree-shaking)**

(You MUST use pure functions that return new dates - NEVER mutate dates with setDate() or similar)

(You MUST use named constants for format strings and durations - NO magic strings like 'yyyy-MM-dd' scattered in code)

</critical_requirements>

Auto-detection: date-fns, format, parseISO, addDays, subMonths, differenceInDays, formatDistance, isAfter, isBefore, eachDayOfInterval, date-fns-tz, @date-fns/tz, @date-fns/utc, TZDate, TZDateMini, UTCDate, UTCDateMini, tz(), transpose, tzName, tzScan, withTimeZone, locale

When to use:

• Formatting dates for display with locale support
• Parsing date strings into Date objects
• Date arithmetic (add/subtract days, months, years)
• Comparing dates and checking intervals
• Calculating differences between dates
• Generating date ranges for calendars
• Relative time formatting ("2 hours ago")

When NOT to use:

• Simple date display - use Intl.DateTimeFormat (zero bundle cost)
• Very simple operations - native Date may suffice
• Complex recurring dates - use rrule.js alongside
• Future projects with Temporal API browser support

Detailed Resources:

• [examples/core.md](examples/core.md) - Formatting, parsing, arithmetic, boundaries, preset ranges
• [examples/timezone.md](examples/timezone.md) - v4 TZDate, v3 date-fns-tz, DST handling, UTC operations
• [examples/i18n.md](examples/i18n.md) - Locale setup, locale-aware formatting, week start days
• [examples/relative.md](examples/relative.md) - Relative time, duration formatting, smart date display
• [examples/comparison.md](examples/comparison.md) - Comparisons, intervals, overlap detection, validation
• [reference.md](reference.md) - Decision frameworks, migration guides, anti-patterns, quick reference

<philosophy>

Philosophy

date-fns is a modular, functional date utility library. Each function is independent, enabling tree-shaking to include only what you use. All functions are pure - they return new Date objects rather than mutating inputs. This makes date operations predictable and testable.

Key principle: Import what you need, let bundlers remove the rest. A simple format import adds ~2KB, not the entire 80KB library.

// Tree-shakeable - only includes format and parseISO
import { format, parseISO } from "date-fns";

// Format constant at module level
const DATE_DISPLAY_FORMAT = "MMMM d, yyyy";

const date = parseISO("2026-01-15");
const display = format(date, DATE_DISPLAY_FORMAT); // "January 15, 2026"

v3+ is 100% TypeScript with built-in type definitions. No @types/date-fns needed.

</philosophy>

<patterns>

Core Patterns

Pattern 1: Format Tokens (Unicode TR35)

date-fns uses Unicode Technical Standard #35 format tokens. These differ from Moment.js (yyyy not YYYY, dd not DD, EEEE not dddd).

import { format } from "date-fns";

// Define format constants at module level
const ISO_DATE_FORMAT = "yyyy-MM-dd";
const DISPLAY_DATE_FORMAT = "MMMM d, yyyy";
const DISPLAY_DATETIME_FORMAT = "MMMM d, yyyy 'at' h:mm a";

const date = new Date(2026, 0, 15, 14, 30, 0);

format(date, ISO_DATE_FORMAT); // "2026-01-15"
format(date, DISPLAY_DATE_FORMAT); // "January 15, 2026"
format(date, DISPLAY_DATETIME_FORMAT); // "January 15, 2026 at 2:30 PM"
format(date, "EEEE"); // "Thursday"
format(date, "h:mm a"); // "2:30 PM"

See [reference.md](reference.md) for the full format token table.

Why good: named constants make format strings reusable and discoverable, Unicode tokens are standard across date libraries

Pattern 2: Locale-Aware Format Shortcuts

Use P, PP, PPP, PPPP for locale-aware date formatting without specifying exact format.

import { format } from "date-fns";
import { enUS, de, ja, fr } from "date-fns/locale";

const date = new Date(2026, 0, 15);

// ✅ Good Example - Locale-aware formatting
// Short date
format(date, "P", { locale: enUS }); // "01/15/2026"
format(date, "P", { locale: de }); // "15.01.2026"
format(date, "P", { locale: ja }); // "2026/01/15"

// Medium date
format(date, "PP", { locale: enUS }); // "Jan 15, 2026"
format(date, "PP", { locale: de }); // "15. Jan. 2026"

// Long date
format(date, "PPP", { locale: enUS }); // "January 15th, 2026"
format(date, "PPP", { locale: fr }); // "15 janvier 2026"

// Full date
format(date, "PPPP", { locale: enUS }); // "Thursday, January 15th, 2026"
format(date, "PPPP", { locale: ja }); // "2026年1月15日木曜日"

// Time shortcuts
format(date, "p", { locale: enUS }); // "12:00 AM"
format(date, "pp", { locale: enUS }); // "12:00:00 AM"

// Combined date and time
format(date, "PPpp", { locale: enUS }); // "Jan 15, 2026, 12:00:00 AM"

Why good: P/PP/PPP adapt to locale conventions automatically, users see dates in familiar format for their region

// ❌ Bad Example - Hardcoded format ignores locale
format(date, "MM/dd/yyyy"); // "01/15/2026" - wrong for most of world!

Why bad: hardcoded MM/dd/yyyy format is US-specific, confusing for European and Asian users who expect different order

Pattern 3: Safe Parsing with parseISO

Use parseISO for ISO 8601 strings. Use parse for custom formats.

import { parseISO, parse, isValid } from "date-fns";

// ✅ Good - parseISO for ISO strings
const date = parseISO("2026-01-15T14:30:00Z");

// ✅ Good - parse for custom formats (3rd arg is reference date)
const CUSTOM_DATE_FORMAT = "dd/MM/yyyy";
const customDate = parse("15/01/2026", CUSTOM_DATE_FORMAT, new Date());

// Always validate parsed dates
if (!isValid(date)) {
  /* handle invalid */
}

Why good: parseISO handles all ISO 8601 variants, isValid catches invalid dates

// ❌ Bad - Using Date constructor
const date1 = new Date("2026-01-15"); // Browser-inconsistent!
const date2 = new Date("01/15/2026"); // May fail in non-US browsers

Why bad: new Date(string) parsing varies by browser and locale

See [examples/core.md](examples/core.md) for strict round-trip parsing that catches invalid dates like Feb 30.

Pattern 4: Date Arithmetic

Use pure functions for date manipulation. All return new Date objects.

import {
  addDays,
  addMonths,
  addYears,
  subDays,
  subMonths,
  subYears,
  addHours,
  addMinutes,
} from "date-fns";

// Duration constants
const WEEK_IN_DAYS = 7;
const BILLING_CYCLE_MONTHS = 1;
const TRIAL_PERIOD_DAYS = 14;

const date = new Date(2026, 0, 15);

// ✅ Good Example - Pure functions return new dates
const nextWeek = addDays(date, WEEK_IN_DAYS); // Jan 22, 2026
const nextMonth = addMonths(date, BILLING_CYCLE_MONTHS); // Feb 15, 2026
const nextYear = addYears(date, 1); // Jan 15, 2027

const lastWeek = subDays(date, WEEK_IN_DAYS); // Jan 8, 2026
const trialEnd = addDays(date, TRIAL_PERIOD_DAYS); // Jan 29, 2026

// Chain operations
const twoWeeksFromNextMonth = addDays(addMonths(date, 1), WEEK_IN_DAYS * 2);

// Original date is unchanged
console.log(date); // Still Jan 15, 2026

Why good: pure functions are predictable and testable, original date unchanged, constants document business logic

// ❌ Bad Example