date-fns - Modular, tree-shakable date utility library for formatting, parsing, and manipulation

npm install date-fns

import { format, parseISO, addDays, differenceInDays } from "date-fns";
 
// Format a date
format(new Date(), "MMMM d, yyyy"); // "April 6, 2026"
 
// Parse ISO string
const date = parseISO("2026-04-06T12:00:00Z");
 
// Add days
const nextWeek = addDays(new Date(), 7);
 
// Difference between dates
const days = differenceInDays(new Date("2026-12-31"), new Date()); // days until end of year

// app/components/ActivityFeed.tsx
"use client";
import {
  format,
  formatDistanceToNow,
  isToday,
  isYesterday,
  isThisWeek,
  parseISO,
} from "date-fns";
 
interface Activity {
  id: string;
  action: string;
  timestamp: string; // ISO string
  user: string;
}
 
const ACTIVITIES: Activity[] = [
  { id: "1", action: "pushed to main", timestamp: new Date().toISOString(), user: "Alice" },
  { id: "2", action: "opened PR #42", timestamp: new Date(Date.now() - 3600000).toISOString(), user: "Bob" },
  { id: "3", action: "merged PR #41", timestamp: new Date(Date.now() - 86400000).toISOString(), user: "Carol" },
  { id: "4", action: "created issue", timestamp: new Date(Date.now() - 259200000).toISOString(), user: "Dave" },
  { id: "5", action: "deployed v2.1", timestamp: "2026-03-20T10:30:00Z", user: "Eve" },
];
 
function formatTimestamp(isoString: string): string {
  const date = parseISO(isoString);
 
  if (isToday(date)) {
    return formatDistanceToNow(date, { addSuffix: true }); // "2 hours ago"
  }
  if (isYesterday(date)) {
    return `Yesterday at ${format(date, "h:mm a")}`; // "Yesterday at 3:30 PM"
  }
  if (isThisWeek(date)) {
    return format(date, "EEEE 'at' h:mm a"); // "Monday at 10:30 AM"
  }
  return format(date, "MMM d, yyyy"); // "Mar 20, 2026"
}
 
export default function ActivityFeed() {
  return (
    <div className="max-w-lg mx-auto p-6">
      <h2 className="text-xl font-bold mb-4">Activity</h2>
      <ul className="space-y-3">
        {ACTIVITIES.map((activity) => (
          <li key={activity.id} className="flex justify-between items-center border-b pb-2">
            <div>
              <span className="font-medium">{activity.user}</span>{" "}
              <span className="text-gray-600">{activity.action}</span>
            </div>
            <time
              dateTime={activity.timestamp}
              className="text-sm text-gray-400 whitespace-nowrap"
            >
              {formatTimestamp(activity.timestamp)}
            </time>
          </li>
        ))}
      </ul>
    </div>
  );
}

import {
  addDays,
  addMonths,
  addHours,
  subWeeks,
  startOfMonth,
  endOfMonth,
  eachDayOfInterval,
} from "date-fns";
 
const tomorrow = addDays(new Date(), 1);
const nextMonth = addMonths(new Date(), 1);
const twoHoursLater = addHours(new Date(), 2);
const lastWeek = subWeeks(new Date(), 1);
 
// Get all days in current month (useful for calendars)
const monthStart = startOfMonth(new Date());
const monthEnd = endOfMonth(new Date());
const daysInMonth = eachDayOfInterval({ start: monthStart, end: monthEnd });

import { format, formatDistanceToNow } from "date-fns";
import { fr } from "date-fns/locale";
import { ja } from "date-fns/locale";
 
format(new Date(), "EEEE d MMMM yyyy", { locale: fr });
// "lundi 6 avril 2026"
 
formatDistanceToNow(new Date(Date.now() - 7200000), {
  addSuffix: true,
  locale: ja,
});
// "約2時間前"

import {
  isWithinInterval,
  isBefore,
  isAfter,
  differenceInCalendarDays,
  differenceInBusinessDays,
  areIntervalsOverlapping,
} from "date-fns";
 
const eventStart = new Date("2026-04-10");
const eventEnd = new Date("2026-04-15");
 
// Check if a date is in range
isWithinInterval(new Date("2026-04-12"), {
  start: eventStart,
  end: eventEnd,
}); // true
 
// Business days between dates (excludes weekends)
differenceInBusinessDays(eventEnd, eventStart); // 3
 
// Check for overlapping intervals
areIntervalsOverlapping(
  { start: eventStart, end: eventEnd },
  { start: new Date("2026-04-13"), end: new Date("2026-04-20") }
); // true

import { parse, isValid } from "date-fns";
 
const date = parse("04/06/2026", "MM/dd/yyyy", new Date());
console.log(isValid(date)); // true
 
const invalid = parse("not-a-date", "MM/dd/yyyy", new Date());
console.log(isValid(invalid)); // false

import type { Locale } from "date-fns";
import { fr } from "date-fns/locale";
 
function formatDate(date: Date | number, locale: Locale = fr): string {
  return format(date, "PPP", { locale });
}