stacks-calendar

name	stacks-calendar
description	Use when working with calendar functionality in Stacks — exporting events to Google Calendar, Outlook, Yahoo, or ICS format, the CalendarLink interface for event definitions, timezone handling, all-day events, or calendar URL generation. Covers @stacksjs/calendar-api.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript
allowed-tools	Read Edit Write Bash Grep Glob

Stacks Calendar

Calendar event export to 4 calendar providers.

Key Paths

• Core package: storage/framework/core/calendar-api/src/
• Package: @stacksjs/calendar-api

Export Functions

import { exportCalendarGoogle, exportCalendarIcs, exportCalendarOutlook, exportCalendarYahoo } from '@stacksjs/calendar-api'

const event: CalendarLink = {
  title: 'Team Meeting',
  description: 'Weekly standup',
  from: new Date('2024-06-15T10:00:00'),
  to: new Date('2024-06-15T11:00:00'),
  address: '123 Main St, City',
  timezone: 'America/New_York',
  allDay: false
}

// Generate URLs
const googleUrl = exportCalendarGoogle(event)
// → https://calendar.google.com/calendar/render?action=TEMPLATE&text=...

const icsContent = exportCalendarIcs(event)
// → BEGIN:VCALENDAR\nBEGIN:VEVENT\n...

const outlookUrl = exportCalendarOutlook(event)
// → https://outlook.live.com/calendar/0/deeplink/compose?...

const yahooUrl = exportCalendarYahoo(event)
// → https://calendar.yahoo.com/?v=60&title=...

CalendarLink Interface

interface CalendarLink {
  title: string
  description?: string
  from: Date              // start time
  to: Date                // end time
  allDay?: boolean        // all-day event (ignores time)
  address?: string        // location
  timezone?: string       // IANA timezone (e.g., 'America/New_York')
}

Calendar Store Types

interface CalendarStore {
  day: number
  month: number
  year: number
  currentMonthYear: string
  datesOfMonth: number[]
  currentWeekView: WeekDates[]
}

interface Events {
  date: string
  title: string
  description?: string
  month: number
  day: number
  year: number
  time?: Time
}

interface Time { from: string, to: string }
interface WeekDates { month: number, date: number }

All-Day Events

const allDayEvent: CalendarLink = {
  title: 'Company Holiday',
  from: new Date('2024-12-25'),
  to: new Date('2024-12-25'),
  allDay: true  // only date matters, no time component
}

Format Differences

Feature	Google	ICS	Outlook	Yahoo
URL-based	Yes	No (file)	Yes	Yes
Timezone	URL param	VTIMEZONE	URL param	URL param
All-day	Date only	DATE value	isAllDay=true	st= format
Description	details=	DESCRIPTION	body=	desc=

Gotchas

• Note package name is @stacksjs/calendar-api (not @stacksjs/calendar)
• ICS export returns file content (not a URL) — serve as .ics download
• All-day events use date-only format, ignoring time components
• Timezone handling varies by provider — ICS includes VTIMEZONE block
• Google Calendar uses UTC format in URLs
• For task scheduling (cron), use @stacksjs/scheduler instead
• ICS generates a unique UID per event for calendar deduplication