Google Calendar Integration

The Google Calendar integration fetches upcoming events from a public Google Calendar and displays them on the website. No OAuth or service account is required -- it uses a simple API key with a publicly shared calendar.

Architecture

Two implementations exist:

1. lib/google-calendar.ts -- Standalone module with in-memory caching (5-minute TTL)
2. lib/server/google-data.ts -- Server component data fetcher using Next.js ISR (5-minute revalidation)

Both call the Google Calendar v3 REST API directly via fetch().

Environment Variables

Setup

GOOGLE_CALENDAR_API_KEY=AIza...
GOOGLE_CALENDAR_ID=mike@josemadridsalsa.com

Data Types

The ScheduleEvent type represents a calendar event:

type ScheduleEvent = {
  id: string
  title: string
  start: string | null
  end: string | null
  location: string | null
  description: string | null
  link: string | null
  isAllDay: boolean
}

All-day events are detected by the presence of start.date without start.dateTime.

API Call

Both implementations call the same endpoint:

GET https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events
  ?key={apiKey}
  &timeMin={now}
  &maxResults=25
  &singleEvents=true
  &orderBy=startTime

• singleEvents=true expands recurring events into individual instances
• orderBy=startTime returns events in chronological order
• Only future events are returned (timeMin is set to the current time)

Caching

Standalone Module (lib/google-calendar.ts)

Uses an in-memory cache with a 5-minute TTL:

const CACHE_TTL_MS = 1000 * 60 * 5

The cache can be manually cleared with clearCalendarCache().

Server Component Fetcher (lib/server/google-data.ts)

Uses Next.js ISR with next: { revalidate: 300 } (5 minutes). Data is embedded in the HTML at render time -- no client-side fetch needed.

Error Handling

The GoogleCalendarNotConfiguredError is thrown when either GOOGLE_CALENDAR_API_KEY or GOOGLE_CALENDAR_ID is missing. The server component fetcher returns an empty array instead of throwing on configuration errors.

Key Files