Date and Timezone Handling: Avoiding Common Pitfalls

Date handling is notoriously tricky. This guide covers best practices for working with dates across timezones.

Golden Rules#

Store in UTC: Always store dates in UTC in your database
Convert on display: Convert to user's timezone only for display
Use ISO 8601: For API communication

Storing Dates#

// Always store as UTC
const now = new Date(); // Already in UTC internally

// PostgreSQL
// Use TIMESTAMP WITH TIME ZONE (TIMESTAMPTZ)
await db.query(`
  INSERT INTO events (name, starts_at)
  VALUES ($1, $2)
`, [name, now.toISOString()]);

Displaying Dates#

// Convert to user's timezone for display
function formatForUser(date: Date, timezone: string): string {
  return new Intl.DateTimeFormat('en-US', {
    timeZone: timezone,
    dateStyle: 'medium',
    timeStyle: 'short',
  }).format(date);
}

formatForUser(new Date(), 'America/New_York');
// "Jan 15, 2024, 3:30 PM"

formatForUser(new Date(), 'Europe/London');
// "Jan 15, 2024, 8:30 PM"

Using date-fns with Timezones#

import { format, parseISO } from 'date-fns';
import { formatInTimeZone, toZonedTime } from 'date-fns-tz';

// Parse ISO string (always UTC)
const date = parseISO('2024-01-15T15:30:00Z');

// Format in specific timezone
const formatted = formatInTimeZone(
  date,
  'America/New_York',
  'MMM d, yyyy h:mm a zzz'
);
// "Jan 15, 2024 10:30 AM EST"

// Get date in specific timezone for calculations
const nyDate = toZonedTime(date, 'America/New_York');

API Communication#

// Always use ISO 8601 format
interface Event {
  id: string;
  name: string;
  startsAt: string; // "2024-01-15T15:30:00Z"
}

// Client sends
const payload = {
  startsAt: selectedDate.toISOString(),
};

// Server responds
const response = {
  startsAt: event.starts_at.toISOString(),
};

Common Pitfalls#

// ❌ Don't create dates from strings without timezone
new Date('2024-01-15'); // Parsed as local midnight, not UTC!

// ✅ Use ISO format with timezone
new Date('2024-01-15T00:00:00Z'); // Explicitly UTC

// ❌ Don't compare dates as strings
'2024-01-15' < '2024-02-01'; // Works but fragile

// ✅ Compare as Date objects
new Date(a).getTime() < new Date(b).getTime();

// ❌ Don't assume user's timezone
const localTime = new Date().toLocaleString(); // Uses browser timezone

// ✅ Explicitly specify timezone
const userTime = new Intl.DateTimeFormat('en-US', {
  timeZone: user.timezone,
}).format(date);

Storing User Timezone#

// Get user's timezone
const userTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
// "America/New_York"

// Store in user profile
await db.users.update({
  where: { id: userId },
  data: { timezone: userTimezone },
});

Date Calculations#

import { addDays, startOfDay, endOfDay } from 'date-fns';
import { zonedTimeToUtc } from 'date-fns-tz';

// Get start of day in user's timezone
function getStartOfDayUTC(date: Date, timezone: string): Date {
  const zonedDate = toZonedTime(date, timezone);
  const startOfZonedDay = startOfDay(zonedDate);
  return zonedTimeToUtc(startOfZonedDay, timezone);
}

// Query for events "today" in user's timezone
const todayStart = getStartOfDayUTC(new Date(), 'America/New_York');
const todayEnd = getStartOfDayUTC(addDays(new Date(), 1), 'America/New_York');

const events = await db.events.findMany({
  where: {
    startsAt: {
      gte: todayStart,
      lt: todayEnd,
    },
  },
});

Testing Dates#

import { vi } from 'vitest';

// Mock current time
vi.useFakeTimers();
vi.setSystemTime(new Date('2024-01-15T12:00:00Z'));

// Test
expect(getCurrentTime()).toBe('2024-01-15T12:00:00.000Z');

vi.useRealTimers();

Store UTC, display local, use ISO 8601, and always be explicit about timezones.

Share this article