date-fns Reference

A modern JavaScript date utility library. Use date-fns for parsing, formatting, and manipulating dates. Version 3.x uses a functional approach with tree-shakeable exports.

Import


interface Event {
  id: string;
  title: string;
  date: string; // ISO 8601 string
}

export default function App() {
  const [events, setEvents] = usePersistentItem<Event[]>("events", []);

  const addEvent = () => {
    const newEvent: Event = {
      id: crypto.randomUUID(),
      title: "New Event",
      date: addDays(new Date(), 7).toISOString(), // Store as ISO string
    };
    setEvents(prev => [...prev, newEvent]);
  };

  const upcomingEvents = events
    .filter(e => isAfter(parseISO(e.date), new Date()))
    .sort((a, b) => parseISO(a.date).getTime() - parseISO(b.date).getTime());

  return (
    <div>
      <button onClick={addEvent}>Add event</button>
      
      {upcomingEvents.map(event => {
        const eventDate = parseISO(event.date);
        const daysUntil = differenceInDays(eventDate, new Date());
        
        return (
          <div key={event.id}>
            <div>
              <h3>{event.title}</h3>
            </div>
            <div>
              <p>{format(eventDate, "EEEE, MMMM d, yyyy")}</p>
              <p className="text-muted-foreground">
                {formatDistanceToNow(eventDate, { addSuffix: true })}
              </p>
              <p className="text-sm">{daysUntil} days away</p>
            </div>
          </div>
        );
      })}
    </div>
  );
}

Best Practices

Store dates as ISO strings - Always use .toISOString() when saving
ALWAYS parse with parseISO (not new Date(string) for stored dates)
Format for display only - Keep dates as Date objects for calculations
Handle timezones carefully - Use date-fns-tz when timezone awareness is needed